modelcontextprotocol/typescript-sdk
Watch
1
0
Fork
You've already forked typescript-sdk
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 1

Refactor McpServer tool registration API

Browse source 
- Remove tool() overload that takes a config object with callback
- Add new registerTool() method that separates config from callback
- Extract common tool registration logic into _createRegisteredTool() helper
- Update all tests to use registerTool() for tools with output schemas
- Update examples to use registerTool() and high-level Client API
- Add comment noting that output schema validation only works with high-level API

This change improves API clarity by using a distinct method for tools with
output schemas while maintaining backward compatibility.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Basil Hosmer 2025-05-14 17:07:50 -04:00
commit 712b04e96d
No known key found for this signature in database
4 changed files with 199 additions and 179 deletions
Download patch file Download diff file Expand all files Collapse all files

41
src/examples/server/mcpServerOutputSchema.ts
View file

@ -16,25 +16,28 @@ const server = new McpServer(
);
// Define a tool with structured output - Weather data
server.tool("get_weather", {
description: "Get weather information for a city",
inputSchema:{
city: z.string().describe("City name"),
country: z.string().describe("Country code (e.g., US, UK)")
server.registerTool(
"get_weather",
{
description: "Get weather information for a city",
inputSchema:{
city: z.string().describe("City name"),
country: z.string().describe("Country code (e.g., US, UK)")
},
outputSchema: {
temperature: z.object({
celsius: z.number(),
fahrenheit: z.number()
}),
conditions: z.enum(["sunny", "cloudy", "rainy", "stormy", "snowy"]),
humidity: z.number().min(0).max(100),
wind: z.object({
speed_kmh: z.number(),
direction: z.string()
})
},
},
outputSchema: {
temperature: z.object({
celsius: z.number(),
fahrenheit: z.number()
}),
conditions: z.enum(["sunny", "cloudy", "rainy", "stormy", "snowy"]),
humidity: z.number().min(0).max(100),
wind: z.object({
speed_kmh: z.number(),
direction: z.string()
})
},
callback: async ({ city, country }) => {
async ({ city, country }) => {
// Parameters are available but not used in this example
void city;
void country;
@ -57,7 +60,7 @@ server.tool("get_weather", {
}
};
}
});
);
async function main() {
const transport = new StdioServerTransport();

22
src/examples/server/testOutputSchemaServers.ts
View file

@ -7,7 +7,6 @@
import { Client } from "../../client/index.js";
import { StdioClientTransport } from "../../client/stdio.js";
import { ListToolsResultSchema, CallToolResultSchema } from "../../types.js";
async function main() {
const serverPath = process.argv[2];
@ -39,9 +38,7 @@ async function main() {
// List available tools
console.log("Listing available tools...");
const toolsResult = await client.request({
method: "tools/list"
}, ListToolsResultSchema);
const toolsResult = await client.listTools();
console.log("Available tools:");
for (const tool of toolsResult.tools) {
@ -56,16 +53,15 @@ async function main() {
// Call the weather tool
console.log("\nCalling get_weather tool...");
const weatherResult = await client.request({
method: "tools/call",
params: {
name: "get_weather",
arguments: {
city: "London",
country: "UK"
}
// Note: Output schema validation only works when using the high-level Client API
// methods like callTool(). Low-level protocol requests do not validate the response.
const weatherResult = await client.callTool({
name: "get_weather",
arguments: {
city: "London",
country: "UK"
}
}, CallToolResultSchema);
});
console.log("\nWeather tool result:");
if (weatherResult.structuredContent) {

132
src/server/mcp.test.ts
View file

@ -463,14 +463,14 @@ describe("tool()", () => {
);
// new api
mcpServer.tool(
mcpServer.registerTool(
"test (new api)",
{
inputSchema: { name: z.string(), value: z.number() },
callback: async ({ name, value }) => ({
content: [{ type: "text", text: `${name}: ${value}` }],
}),
}
{
inputSchema: { name: z.string(), value: z.number() },
},
async ({ name, value }) => ({
content: [{ type: "text", text: `${name}: ${value}` }],
})
);
const [clientTransport, serverTransport] =
@ -525,9 +525,12 @@ describe("tool()", () => {
}));
// new api
mcpServer.tool("test (new api)", {
description: "Test description",
callback: async () => ({
mcpServer.registerTool(
"test (new api)",
{
description: "Test description",
},
async () => ({
content: [
{
type: "text" as const,
@ -535,7 +538,7 @@ describe("tool()", () => {
},
],
})
});
);
const [clientTransport, serverTransport] =
@ -582,17 +585,20 @@ describe("tool()", () => {
],
}));
mcpServer.tool("test (new api)", {
annotations: { title: "Test Tool", readOnlyHint: true },
callback: async () => ({
mcpServer.registerTool(
"test (new api)",
{
annotations: { title: "Test Tool", readOnlyHint: true },
},
async () => ({
content: [
{
type: "text" as const,
text: "Test response",
},
],
}),
});
})
);
const [clientTransport, serverTransport] =
InMemoryTransport.createLinkedPair();
@ -638,13 +644,16 @@ describe("tool()", () => {
})
);
mcpServer.tool("test (new api)", {
inputSchema: { name: z.string() },
annotations: { title: "Test Tool", readOnlyHint: true },
callback: async ({ name }) => ({
mcpServer.registerTool(
"test (new api)",
{
inputSchema: { name: z.string() },
annotations: { title: "Test Tool", readOnlyHint: true },
},
async ({ name }) => ({
content: [{ type: "text", text: `Hello, ${name}!` }]
})
});
);
const [clientTransport, serverTransport] =
InMemoryTransport.createLinkedPair();
@ -694,14 +703,17 @@ describe("tool()", () => {
})
);
mcpServer.tool("test (new api)", {
description: "A tool with everything",
inputSchema: { name: z.string() },
annotations: { title: "Complete Test Tool", readOnlyHint: true, openWorldHint: false },
callback: async ({ name }) => ({
mcpServer.registerTool(
"test (new api)",
{
description: "A tool with everything",
inputSchema: { name: z.string() },
annotations: { title: "Complete Test Tool", readOnlyHint: true, openWorldHint: false },
},
async ({ name }) => ({
content: [{ type: "text", text: `Hello, ${name}!` }]
})
});
);
const [clientTransport, serverTransport] =
InMemoryTransport.createLinkedPair();
@ -757,14 +769,17 @@ describe("tool()", () => {
})
);
mcpServer.tool("test (new api)", {
description: "A tool with everything but empty params",
inputSchema: {},
annotations: { title: "Complete Test Tool with empty params", readOnlyHint: true, openWorldHint: false },
callback: async () => ({
mcpServer.registerTool(
"test (new api)",
{
description: "A tool with everything but empty params",
inputSchema: {},
annotations: { title: "Complete Test Tool with empty params", readOnlyHint: true, openWorldHint: false },
},
async () => ({
content: [{ type: "text" as const, text: "Test response" }]
})
});
);
const [clientTransport, serverTransport] =
InMemoryTransport.createLinkedPair();
@ -834,20 +849,23 @@ describe("tool()", () => {
}),
);
mcpServer.tool("test (new api)", {
inputSchema: {
name: z.string(),
value: z.number(),
mcpServer.registerTool(
"test (new api)",
{
inputSchema: {
name: z.string(),
value: z.number(),
},
},
callback: async ({ name, value }) => ({
async ({ name, value }) => ({
content: [
{
type: "text",
text: `${name}: ${value}`,
},
],
}),
});
})
);
const [clientTransport, serverTransport] =
InMemoryTransport.createLinkedPair();
@ -958,7 +976,7 @@ describe("tool()", () => {
);
// Register a tool with outputSchema
mcpServer.tool(
mcpServer.registerTool(
"test",
{
description: "Test tool with structured output",
@ -970,14 +988,14 @@ describe("tool()", () => {
resultType: z.string(),
timestamp: z.string()
},
callback: async ({ input }) => ({
structuredContent: {
processedInput: input,
resultType: "structured",
timestamp: "2023-01-01T00:00:00Z"
},
}),
},
async ({ input }) => ({
structuredContent: {
processedInput: input,
resultType: "structured",
timestamp: "2023-01-01T00:00:00Z"
},
})
);
const [clientTransport, serverTransport] =
@ -1061,7 +1079,7 @@ describe("tool()", () => {
);
// Register a tool with outputSchema that returns invalid data
mcpServer.tool(
mcpServer.registerTool(
"test",
{
description: "Test tool with invalid structured output",
@ -1073,15 +1091,15 @@ describe("tool()", () => {
resultType: z.string(),
timestamp: z.string()
},
callback: async ({ input }) => ({
structuredContent: {
processedInput: input,
resultType: "structured",
// Missing required 'timestamp' field
someExtraField: "unexpected" // Extra field not in schema
},
}),
},
async ({ input }) => ({
structuredContent: {
processedInput: input,
resultType: "structured",
// Missing required 'timestamp' field
someExtraField: "unexpected" // Extra field not in schema
},
})
);
const [clientTransport, serverTransport] =

193
src/server/mcp.ts
View file

@ -219,14 +219,6 @@ export class McpServer {
];
}
} else {
// Tool has no outputSchema
if (result.structuredContent) {
throw new McpError(
ErrorCode.InternalError,
`Tool ${request.params.name} has no outputSchema but returned structuredContent`,
);
}
// Tool must have content if no outputSchema
if (!result.content && !result.isError) {
throw new McpError(
@ -647,6 +639,47 @@ export class McpServer {
}
}
private _createRegisteredTool(
name: string,
description: string | undefined,
inputSchema: ZodRawShape | undefined,
outputSchema: ZodRawShape | undefined,
annotations: ToolAnnotations | undefined,
callback: ToolCallback<ZodRawShape | undefined>
): RegisteredTool {
const registeredTool: RegisteredTool = {
description,
inputSchema:
inputSchema === undefined ? undefined : z.object(inputSchema),
outputSchema:
outputSchema === undefined ? undefined : z.object(outputSchema),
annotations,
callback,
enabled: true,
disable: () => registeredTool.update({ enabled: false }),
enable: () => registeredTool.update({ enabled: true }),
remove: () => registeredTool.update({ name: null }),
update: (updates) => {
if (typeof updates.name !== "undefined" && updates.name !== name) {
delete this._registeredTools[name]
if (updates.name) this._registeredTools[updates.name] = registeredTool
}
if (typeof updates.description !== "undefined") registeredTool.description = updates.description
if (typeof updates.paramsSchema !== "undefined") registeredTool.inputSchema = z.object(updates.paramsSchema)
if (typeof updates.callback !== "undefined") registeredTool.callback = updates.callback
if (typeof updates.annotations !== "undefined") registeredTool.annotations = updates.annotations
if (typeof updates.enabled !== "undefined") registeredTool.enabled = updates.enabled
this.sendToolListChanged()
},
};
this._registeredTools[name] = registeredTool;
this.setToolRequestHandlers();
this.sendToolListChanged()
return registeredTool
}
/**
* Registers a zero-argument tool `name`, which will run the given function when the client calls it.
*/
@ -703,22 +736,9 @@ export class McpServer {
description: string,
paramsSchema: Args,
annotations: ToolAnnotations,
callback: ToolCallback<Args>,
cb: ToolCallback<Args>,
): RegisteredTool;
/**
* Registers a tool from a config object.
*/
tool<InputArgs extends ZodRawShape, OutputArgs extends ZodRawShape>(
name: string,
config: {
description?: string;
inputSchema?: InputArgs;
outputSchema?: OutputArgs;
annotations?: ToolAnnotations;
callback: ToolCallback<InputArgs>
}
): RegisteredTool;
/**
* tool() implementation. Parses arguments passed to overrides defined above.
@ -732,86 +752,69 @@ export class McpServer {
let inputSchema: ZodRawShape | undefined;
let outputSchema: ZodRawShape | undefined;
let annotations: ToolAnnotations | undefined;
let callback: ToolCallback<ZodRawShape | undefined>;
if (rest.length == 1 && typeof rest[0] === "object" && rest[0] !== null && 'callback' in rest[0]) {
// New style: tool(name, { description, inputSchema, outputSchema, annotations, callback })
// Future additions to tool definition should be added to config object.
// Tool properties are passed as separate arguments, with omissions allowed.
// Support for this style is frozen as of protocol version 2025-03-26. Future additions
// to tool definition should *NOT* be added.
const config = rest[0] as {
description?: string;
inputSchema?: ZodRawShape;
outputSchema?: ZodRawShape;
annotations?: ToolAnnotations;
callback: ToolCallback<ZodRawShape>;
};
({ description, inputSchema, outputSchema, annotations, callback } = config) ;
} else {
// Old style: tool properties are passed as separate arguments, with omissions allowed.
// Support for this style is frozen as of protocol version 2025-03-26. Future additions
// to tool definition should *NOT* be added.
if (typeof rest[0] === "string") {
description = rest.shift() as string;
}
// Handle the different overload combinations
if (rest.length > 1) {
// We have at least one more arg before the callback
const firstArg = rest[0];
if (isZodRawShape(firstArg)) {
// We have a params schema as the first arg
inputSchema = rest.shift() as ZodRawShape;
// Check if the next arg is potentially annotations
if (rest.length > 1 && typeof rest[0] === "object" && rest[0] !== null && !(isZodRawShape(rest[0]))) {
// Case: tool(name, paramsSchema, annotations, cb)
// Or: tool(name, description, paramsSchema, annotations, cb)
annotations = rest.shift() as ToolAnnotations;
}
} else if (typeof firstArg === "object" && firstArg !== null) {
// Not a ZodRawShape, so must be annotations in this position
// Case: tool(name, annotations, cb)
// Or: tool(name, description, annotations, cb)
annotations = rest.shift() as ToolAnnotations;
}
}
callback = rest[0] as ToolCallback<ZodRawShape | undefined>;
if (typeof rest[0] === "string") {
description = rest.shift() as string;
}
const registeredTool: RegisteredTool = {
description,
inputSchema:
inputSchema === undefined ? undefined : z.object(inputSchema),
outputSchema:
outputSchema === undefined ? undefined : z.object(outputSchema),
annotations,
callback: callback,
enabled: true,
disable: () => registeredTool.update({ enabled: false }),
enable: () => registeredTool.update({ enabled: true }),
remove: () => registeredTool.update({ name: null }),
update: (updates) => {
if (typeof updates.name !== "undefined" && updates.name !== name) {
delete this._registeredTools[name]
if (updates.name) this._registeredTools[updates.name] = registeredTool
// Handle the different overload combinations
if (rest.length > 1) {
// We have at least one more arg before the callback
const firstArg = rest[0];
if (isZodRawShape(firstArg)) {
// We have a params schema as the first arg
inputSchema = rest.shift() as ZodRawShape;
// Check if the next arg is potentially annotations
if (rest.length > 1 && typeof rest[0] === "object" && rest[0] !== null && !(isZodRawShape(rest[0]))) {
// Case: tool(name, paramsSchema, annotations, cb)
// Or: tool(name, description, paramsSchema, annotations, cb)
annotations = rest.shift() as ToolAnnotations;
}
if (typeof updates.description !== "undefined") registeredTool.description = updates.description
if (typeof updates.paramsSchema !== "undefined") registeredTool.inputSchema = z.object(updates.paramsSchema)
if (typeof updates.callback !== "undefined") registeredTool.callback = updates.callback
if (typeof updates.annotations !== "undefined") registeredTool.annotations = updates.annotations
if (typeof updates.enabled !== "undefined") registeredTool.enabled = updates.enabled
this.sendToolListChanged()
},
};
this._registeredTools[name] = registeredTool;
} else if (typeof firstArg === "object" && firstArg !== null) {
// Not a ZodRawShape, so must be annotations in this position
// Case: tool(name, annotations, cb)
// Or: tool(name, description, annotations, cb)
annotations = rest.shift() as ToolAnnotations;
}
}
const callback = rest[0] as ToolCallback<ZodRawShape | undefined>;
this.setToolRequestHandlers();
this.sendToolListChanged()
return this._createRegisteredTool(name, description, inputSchema, outputSchema, annotations, callback)
}
return registeredTool
/**
* Registers a tool with a config object and callback.
*/
registerTool<InputArgs extends ZodRawShape, OutputArgs extends ZodRawShape>(
name: string,
config: {
description?: string;
inputSchema?: InputArgs;
outputSchema?: OutputArgs;
annotations?: ToolAnnotations;
},
cb: ToolCallback<InputArgs>
): RegisteredTool {
if (this._registeredTools[name]) {
throw new Error(`Tool ${name} is already registered`);
}
const { description, inputSchema, outputSchema, annotations } = config;
return this._createRegisteredTool(
name,
description,
inputSchema,
outputSchema,
annotations,
cb as ToolCallback<ZodRawShape | undefined>
)
}
/**