Skip to content

Commit ff438df

Browse files
travisbreaksclaude
andcommitted
fix: allow named interfaces for structuredContent in tool callbacks
TypeScript does not allow named interfaces to be assigned to index signatures (Record<string, unknown>), even when all properties are compatible. This meant that returning a named interface as structuredContent in a tool callback caused a type error, while inline object types worked fine. Introduces ToolCallbackResult, which uses `object` instead of Record<string, unknown> for the structuredContent field in the callback return position. The Zod schema remains unchanged for runtime validation. Adds a compile-time type test in mcp.examples.ts verifying that named interfaces work as structuredContent without type casts. Fixes modelcontextprotocol#837 Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>
1 parent ccb78f2 commit ff438df

3 files changed

Lines changed: 65 additions & 1 deletion

File tree

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
---
2+
'@modelcontextprotocol/server': patch
3+
---
4+
5+
fix: allow named interfaces for structuredContent in tool callbacks
6+
7+
Previously, returning a named interface type (e.g., `interface MyResult { data: string }`)
8+
as `structuredContent` in a tool callback caused a TypeScript error because TypeScript
9+
does not allow named interfaces to be assigned to `Record<string, unknown>` index signatures.
10+
Inline object types worked fine, making this an inconsistent developer experience.
11+
12+
The fix introduces a `ToolCallbackResult` type that uses `object` instead of
13+
`Record<string, unknown>` for the `structuredContent` field in the callback return position,
14+
while keeping the Zod schema unchanged for runtime validation.

‎packages/server/src/server/mcp.examples.ts‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -122,6 +122,44 @@ async function McpServer_sendLoggingMessage_basic(server: McpServer) {
122122
//#endregion McpServer_sendLoggingMessage_basic
123123
}
124124

125+
/**
126+
* Example: Using a named interface for structuredContent (verifies fix for #837).
127+
*
128+
* Named interfaces should be assignable to the structuredContent field
129+
* without requiring type casts. Previously, this caused a type error because
130+
* TypeScript does not allow named interfaces to be assigned to index signatures.
131+
*/
132+
interface BmiResult {
133+
bmi: number;
134+
category: string;
135+
}
136+
137+
function McpServer_registerTool_structuredContent_named_interface(server: McpServer) {
138+
server.registerTool(
139+
'calculate-bmi-named',
140+
{
141+
title: 'BMI Calculator (named interface)',
142+
description: 'Calculate BMI, returning a named interface type',
143+
inputSchema: z.object({
144+
weightKg: z.number(),
145+
heightM: z.number()
146+
}),
147+
outputSchema: z.object({ bmi: z.number(), category: z.string() })
148+
},
149+
async ({ weightKg, heightM }) => {
150+
const bmi = weightKg / (heightM * heightM);
151+
const result: BmiResult = {
152+
bmi,
153+
category: bmi < 18.5 ? 'underweight' : bmi < 25 ? 'normal' : 'overweight'
154+
};
155+
return {
156+
content: [{ type: 'text', text: JSON.stringify(result) }],
157+
structuredContent: result
158+
};
159+
}
160+
);
161+
}
162+
125163
/**
126164
* Example: Logging from inside a tool handler via ctx.mcpReq.log().
127165
*/

‎packages/server/src/server/mcp.ts‎

Lines changed: 13 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1068,10 +1068,22 @@ export type BaseToolCallback<ResultT extends Result, Ctx extends ServerContext,
10681068
? (args: SchemaOutput<Args>, ctx: Ctx) => ResultT | Promise<ResultT>
10691069
: (ctx: Ctx) => ResultT | Promise<ResultT>;
10701070

1071+
/**
1072+
* A more permissive version of {@linkcode CallToolResult} for use in tool callback return types.
1073+
*
1074+
* Uses `object` instead of `Record<string, unknown>` for `structuredContent` so that
1075+
* named interfaces (not just inline object types) can be returned without type errors.
1076+
* This is necessary because TypeScript does not allow named interfaces to be assigned
1077+
* to index signatures (`Record<string, unknown>`), even when all properties are compatible.
1078+
*/
1079+
export type ToolCallbackResult = Omit<CallToolResult, 'structuredContent'> & {
1080+
structuredContent?: object;
1081+
};
1082+
10711083
/**
10721084
* Callback for a tool handler registered with {@linkcode McpServer.registerTool}.
10731085
*/
1074-
export type ToolCallback<Args extends AnySchema | undefined = undefined> = BaseToolCallback<CallToolResult, ServerContext, Args>;
1086+
export type ToolCallback<Args extends AnySchema | undefined = undefined> = BaseToolCallback<ToolCallbackResult, ServerContext, Args>;
10751087

10761088
/**
10771089
* Supertype that can handle both regular tools (simple callback) and task-based tools (task handler object).

0 commit comments

Comments
 (0)