Skip to content

feat(server): support json schema to define tool parameters #423

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from

Conversation

kombucha
Copy link

@kombucha kombucha commented Apr 28, 2025

Adds the ability to define tool parameters in json schema directly

Motivation and Context

Fixes #283

The typescript-sdk uses Zod to validate the parameters passed to tools and generates a json schema representation from it for the MCP client. There are cases where you might want to define tools directly with a JSON Schema: for example, when generating mcp tools dynamically from an OpenAPI Specification (example here). In these cases, you have to go from json schema, to Zod and back to json schema which is wasteful and hard to do without losing information along the way (for example, when you have recursive types).

Example usage

mcpServer.tool({
  name: "hello",
  paramsSchema: {
    type: "object",
    properties: { name: { type: "string" } },
    additionalProperties: false
  },
  cb: async (args) => ({
    content: [{ type: "text", text: `Hello, ${args.name}!` }]
  })
});

How Has This Been Tested?

  • Existing tests are still passing ✅
  • Added a test to make sure the new tool definition signature works correctly ✅
  • Added a test to make sure tool arg validation works correctly ✅
  • Tested a dummy tool defined with JSON Schema in Claude Desktop ✅

Breaking Changes

None, the changes are intended to only be additive.

Types of changes

  • Bug fix (non-breaking change which fixes an issue)
  • New feature (non-breaking change which adds functionality)
  • Breaking change (fix or feature that would cause existing functionality to change)
  • Documentation update

Checklist

  • I have read the MCP Documentation
  • My code follows the repository's style guidelines
  • New and existing tests pass locally
  • I have added appropriate error handling
  • I have added or updated documentation as needed

Additional context

  • When using JSON Schema, you lose the ability to properly type the tool args (which is just marked as object).
  • I added ajv as a dependency, which seems to be the reference when working with JSON Schema in Node.js
  • I added a new function overload for MCPServer#tool() which accepts a configuration object instead of positional arguments. I only did that because I struggled to make the types work with positional arguments. Notably, I was losing type inference with the ToolCallback conditional type. Typescript does seem to infer types correctly when using the object version though. And while I understand it's completely subjective, I think having an object version makes for a nicer API (without removing previous options) and it would address Allow passing a Tool object to the server.tool() method #369
  • Moved some functions around in mcp.ts to keep the methods from growing too much from the additional complexity

@kombucha kombucha force-pushed the feat-support-json-schema branch from d85a794 to 2ff2e88 Compare April 28, 2025 21:40
@kombucha kombucha marked this pull request as draft April 28, 2025 21:44
@kombucha kombucha force-pushed the feat-support-json-schema branch from 2ff2e88 to 2f85e25 Compare April 28, 2025 21:46
@kombucha kombucha marked this pull request as ready for review April 28, 2025 21:59
@@ -130,3 +130,5 @@ out

.DS_Store
dist/

.vscode
Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Unrelated to the PR, but I had to stop my vscode from trying to format files with Prettier and removing random trailing whitespace.
Happy to remove that change and keep it for a separate PR!

@kombucha kombucha changed the title feat(server): support json schema to validate define tool parameters feat(server): support json schema to define tool parameters Apr 30, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Support JSON schema in addition to zod
1 participant