feat(mcp): support tool output schema

[akitaSummer]

Checklist

• npm test passes
• tests and/or benchmarks are included
• documentation is changed or added
• commit message follows commit guidelines

Affected core subsystem(s)

Description of change

Summary by CodeRabbit

• New Features

  • Added optional output schemas for MCP tools.
  • MCP tools can now return validated, structured output alongside text responses.
  • Added type-safe success and error responses based on declared output schemas.
  • Registered schemas are now exposed and validated when tools are called.

• Documentation

  • Updated MCP controller examples to demonstrate structured tool output and schema declarations.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 70f20d12-6241-422a-ba1b-3cd781702835

📥 Commits

Reviewing files that changed from the base of the PR and between 50de107 and c9aaeee.

📒 Files selected for processing (10)

• core/controller-decorator/src/model/MCPToolMeta.ts
• core/controller-decorator/test/MCPMeta.test.ts
• core/controller-decorator/test/fixtures/MCPController.ts
• core/types/controller-decorator/MCPToolParams.ts
• plugin/controller/README.md
• plugin/controller/lib/impl/mcp/MCPServerHelper.ts
• plugin/controller/test/mcp/helper.test.ts
• standalone/service-worker/src/mcp/MCPServerHelper.ts
• standalone/service-worker/test/fixtures/mcp/MCPTestController.ts
• standalone/service-worker/test/mcp/mcp.test.ts

---

📝 Walkthrough

Walkthrough

MCP tools now support optional output schemas. Metadata, response types, server registration, structured output, and validation tests were updated across controller and service-worker implementations.

Changes

MCP output schema support

Layer / File(s)	Summary
Output schema contracts and metadata core/types/controller-decorator/MCPToolParams.ts, core/controller-decorator/src/model/MCPToolMeta.ts, core/controller-decorator/test/*	MCP parameters and metadata now carry optional output schemas. MCPToolResponse provides schema-dependent structured response types.
Controller registration and output validation plugin/controller/lib/impl/mcp/MCPServerHelper.ts, plugin/controller/test/mcp/helper.test.ts	Controller tool registration passes output schemas to MCP. Tests verify schema exposure, structured output, and validation errors for invalid output.
Service-worker integration and examples standalone/service-worker/src/mcp/MCPServerHelper.ts, standalone/service-worker/test/*, plugin/controller/README.md	The service-worker registration passes output schemas. Fixtures and documentation show typed structured output responses.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Sequence Diagram(s)

sequenceDiagram
  participant MCPClient
  participant MCPServerHelper
  participant RegisteredMCPTool
  participant OutputSchema
  MCPClient->>MCPServerHelper: call MCP tool
  MCPServerHelper->>RegisteredMCPTool: execute handler
  RegisteredMCPTool->>OutputSchema: validate structuredContent
  OutputSchema-->>RegisteredMCPTool: valid output or validation error
  RegisteredMCPTool-->>MCPClient: return content and structuredContent or error

Loading

Possibly related PRs

• eggjs/tegg#321: Both changes modify MCPServerHelper.mcpToolRegister.
• eggjs/tegg#463: Both changes extend MCP tool metadata and registration configuration.

Suggested reviewers: killagu

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the PR's main change: adding support for MCP tool output schemas.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/mcp-output-schema

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 ESLint

If the error stems from missing dependencies, add them to the package.json file. For unrecoverable errors (e.g., due to private dependencies), disable the tool in the CodeRabbit configuration.

core/controller-decorator/src/model/MCPToolMeta.ts

ESLint skipped: missing config or dependency (missing-dependency). The ESLint configuration references a package that is not available in the sandbox.

core/controller-decorator/test/MCPMeta.test.ts

ESLint skipped: the ESLint configuration for this file references a package that is not available in the sandbox.

core/controller-decorator/test/fixtures/MCPController.ts

ESLint skipped: the ESLint configuration for this file references a package that is not available in the sandbox.

• 6 others

---

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.}