feat(mcp): use GraphQL operation descriptions for MCP tool descriptions

[asoorm]

Extract and use operation descriptions from GraphQL files to provide better context for MCP tools. Operations without descriptions fall back to the default format.

• Extract descriptions during operation loading
• Merge operation and schema descriptions
• Add tests for description extraction and usage

partially addresses #2213

Summary by CodeRabbit

• New Features

  • Extract and surface operation descriptions from GraphQL operations for use in tool descriptions.

• Bug Fixes

  • Use the exact operation description when present; otherwise fall back to a concise default format.
  • Preserve explicit operation descriptions instead of overwriting them with schema defaults.

• Tests

  • Added tests covering multi-line, single-line, empty descriptions and description-selection logic.

• Chores

  • Updated dependency versions.

[coderabbitai]

Walkthrough

Extracts per-operation descriptions from GraphQL operation files, attach them to Operation objects, prefer those descriptions for MCP tool descriptions (falling back to generated/schema text when empty), add unit tests for extraction and description-selection, and update module dependency versions.

Changes

Cohort / File(s)	Summary
Schema/Operation Loading router/pkg/schemaloader/loader.go, router/pkg/schemaloader/schema_builder.go	Extract per-operation Description from GraphQL operation definitions and assign to Operation.Description; adjust operation name retrieval; only apply schema-level description when operation description is empty.
Schemaloader Tests router/pkg/schemaloader/loader_test.go	Add tests that create operation files with multi-line, single-line, and missing descriptions; verify correct loading, skipping of invalid operations, and empty-directory behavior.
MCP Tool Registration router/pkg/mcpserver/server.go	Use an operation's non-empty Description verbatim as the MCP tool description; retain existing fallback formatting when description is absent.
MCP Tool Tests router-tests/mcp_test.go	Update expected tool descriptions and add test suites "Operation Description Extraction" and "Tool Description Usage" to validate extraction and precedence (use operation description if present, otherwise fallback text).
Dependency Updates router/go.mod, router-tests/go.mod	Bump several module versions (grpc, golang.org/x/exp, genproto, and related indirects); adjust require/indirect entries accordingly.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

• Check extractOperationDescription() AST handling for multi-line and single-line description edge cases and proper trimming.
• Verify schema_builder.go logic only overrides when operation description is empty.
• Review tests for correct setup/teardown of temp files and accurate assertions for description precedence.
• Confirm mcpserver/server.go change only impacts the tool description text and does not alter tool identifiers or other metadata.

Pre-merge checks

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title Check	✅ Passed	The pull request title "feat(mcp): use GraphQL operation descriptions for MCP tool descriptions" is fully related to and clearly summarizes the main change in the changeset. The implementation across multiple files demonstrates exactly this: extracting operation descriptions from GraphQL files (in loader.go), using those descriptions directly for MCP tool descriptions (in server.go), and providing a fallback to default descriptions when none are provided. The title is concise, specific, and follows conventional commit format, making it easy for teammates to understand the primary change when scanning history.
Docstring Coverage	✅ Passed	Docstring coverage is 83.33% which is sufficient. The required threshold is 80.00%.

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 578e288 and 753d054.

⛔ Files ignored due to path filters (1)

• router/go.sum is excluded by !**/*.sum

📒 Files selected for processing (1)

• router/go.mod (3 hunks)

🧰 Additional context used

🧠 Learnings (3)

📚 Learning: 2025-09-24T12:54:00.765Z

Learnt from: endigma
PR: wundergraph/cosmo#2222
File: router-tests/websocket_test.go:2238-2302
Timestamp: 2025-09-24T12:54:00.765Z
Learning: The wundergraph/cosmo project uses Go 1.25 (Go 1.23+ minimum), so fmt.Appendf and other newer Go standard library functions are available and can be used without compatibility concerns.

Applied to files:

• router/go.mod

📚 Learning: 2025-09-24T12:54:00.765Z

Learnt from: endigma
PR: wundergraph/cosmo#2222
File: router-tests/websocket_test.go:2238-2302
Timestamp: 2025-09-24T12:54:00.765Z
Learning: The wundergraph/cosmo project uses Go 1.25 (Go 1.25 minimum), so fmt.Appendf and other newer Go standard library functions are available and can be used without compatibility concerns.

Applied to files:

• router/go.mod

📚 Learning: 2025-08-20T22:13:25.222Z

Learnt from: StarpTech
PR: wundergraph/cosmo#2157
File: router-tests/go.mod:16-16
Timestamp: 2025-08-20T22:13:25.222Z
Learning: github.com/mark3labs/mcp-go v0.38.0 has regressions and should not be used in the wundergraph/cosmo project. v0.36.0 is the stable version that should be used across router-tests and other modules.

Applied to files:

• router/go.mod

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (8)

• GitHub Check: build_test
• GitHub Check: image_scan (nonroot)
• GitHub Check: integration_test (./. ./fuzzquery ./lifecycle ./modules)
• GitHub Check: build_push_image
• GitHub Check: build_push_image (nonroot)
• GitHub Check: image_scan
• GitHub Check: Analyze (go)
• GitHub Check: Analyze (javascript-typescript)

🔇 Additional comments (1)

router/go.mod (1)

55-55: Verify the justification and compatibility of dependency version bumps.

The changes bump several key dependencies (grpc from v1.68.1 → v1.71.0, golang.org/x/exp, and genproto indirect dependencies), but the PR objectives focus on GraphQL operation description extraction for MCP tools—these version changes aren't mentioned as necessary for that feature. The mcp-go version at line 76 correctly remains at v0.36.0 per project guidelines.

Before merging, clarify whether these dependency updates are:

1. Required to support the operation description feature, or
2. Incidental maintenance updates that should be in a separate PR

If required, confirm these versions are compatible and free of regressions relevant to the router module. Based on learnings, confirmed v0.36.0 is the stable mcp-go version.

Also applies to: 85-85, 169-170

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[github-actions]

Router image scan passed

✅ No security vulnerabilities found in image:

ghcr.io/wundergraph/cosmo/router:sha-23327eb78854717ccc0efcf6c95306e2b737b226

[github-actions]

Router-nonroot image scan passed

✅ No security vulnerabilities found in image:

ghcr.io/wundergraph/cosmo/router:sha-093c116294beebf629170b8af5ecdde25c3c133e-nonroot

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

router-tests/mcp_test.go (1)

704-757: Consider testing the actual description selection logic.

This test simulates the description selection logic inline (lines 742-747) rather than invoking the actual implementation from server.go. This creates a maintenance risk: if the server's description selection logic changes, this test might still pass even though the actual behavior differs.

Consider one of these approaches:

1. Extract the description selection logic in server.go into a package-level or exported function that can be called from this test.
2. Use the existing integration test structure (like "List User Operations" on line 119) to verify description usage end-to-end, which already validates that operation descriptions are correctly used in tool listings.

Option 2 may be preferable since lines 119-161 already provide integration-level verification of the feature.

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 2a0ad8b and b3e0a2b.

📒 Files selected for processing (2)

• router-tests/mcp_test.go (5 hunks)
• router/pkg/mcpserver/server.go (1 hunks)

🚧 Files skipped from review as they are similar to previous changes (1)

• router/pkg/mcpserver/server.go

🧰 Additional context used

🧠 Learnings (1)

📚 Learning: 2025-08-20T22:13:25.222Z

Learnt from: StarpTech
PR: wundergraph/cosmo#2157
File: router-tests/go.mod:16-16
Timestamp: 2025-08-20T22:13:25.222Z
Learning: github.com/mark3labs/mcp-go v0.38.0 has regressions and should not be used in the wundergraph/cosmo project. v0.36.0 is the stable version that should be used across router-tests and other modules.

Applied to files:

• router-tests/mcp_test.go

🧬 Code graph analysis (1)

router-tests/mcp_test.go (1)

router/pkg/schemaloader/loader.go (2)

• NewOperationLoader (38-43)
• Operation (19-27)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (11)

• GitHub Check: build-router
• GitHub Check: Analyze (javascript-typescript)
• GitHub Check: Analyze (go)
• GitHub Check: integration_test (./. ./fuzzquery ./lifecycle ./modules)
• GitHub Check: build_push_image (nonroot)
• GitHub Check: build_push_image
• GitHub Check: image_scan (nonroot)
• GitHub Check: image_scan
• GitHub Check: build_test
• GitHub Check: integration_test (./events)
• GitHub Check: integration_test (./telemetry)

🔇 Additional comments (2)

router-tests/mcp_test.go (2)

7-8: LGTM!

The new imports are appropriate for the added test functionality: file operations for creating temporary test files, GraphQL parsing utilities for schema and operation handling, and logging for the operation loader.

Also applies to: 19-22

---

564-702: Excellent test coverage for operation description extraction.

This test suite thoroughly validates description extraction from GraphQL operations, covering multi-line descriptions, single-line descriptions, operations without descriptions, and mutations. The integration with the actual schemaloader provides confidence that the feature works end-to-end.