feat: update TypeScript SDK to implement draft spec changes for structured tool output

- Add outputSchema support to Tool interface with proper documentation - Split CallToolResult into structured and unstructured variants - Change structuredContent from string to object type - Add validation that tools without outputSchema cannot return structuredContent - Add validation that tools with outputSchema must return structuredContent - Update client to validate structured content as object (no JSON parsing) - Update tests to use object format for structuredContent - Add tests for new validation constraints - Update LATEST_PROTOCOL_VERSION to DRAFT-2025-v2 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>

Author: bhosmer-ant

src/client/auth.test.ts

@@ -39,7 +39,7 @@ describe("OAuth Authorization", () => {
  const [url, options] = calls[0];
  expect(url.toString()).toBe("https://auth.example.com/.well-known/oauth-authorization-server");
  expect(options.headers).toEqual({
- "MCP-Protocol-Version": "2025-03-26"
+ "MCP-Protocol-Version": "DRAFT-2025-v2"
  });
  });
 

src/client/index.test.ts

@@ -802,7 +802,7 @@ describe('outputSchema validation', () => {
  server.setRequestHandler(CallToolRequestSchema, async (request) => {
  if (request.params.name === 'test-tool') {
  return {
- structuredContent: JSON.stringify({ result: 'success', count: 42 }),
+ structuredContent: { result: 'success', count: 42 },
  };
  }
  throw new Error('Unknown tool');
@@ -825,7 +825,7 @@ describe('outputSchema validation', () => {
 
  // Call the tool - should validate successfully
  const result = await client.callTool({ name: 'test-tool' });
- expect(result.structuredContent).toBe('{"result":"success","count":42}');
+ expect(result.structuredContent).toEqual({ result: 'success', count: 42 });
  });
 
  test('should throw error when structuredContent does not match schema', async () => {
@@ -874,7 +874,7 @@ describe('outputSchema validation', () => {
  if (request.params.name === 'test-tool') {
  // Return invalid structured content (count is string instead of number)
  return {
- structuredContent: JSON.stringify({ result: 'success', count: 'not a number' }),
+ structuredContent: { result: 'success', count: 'not a number' },
  };
  }
  throw new Error('Unknown tool');
@@ -1094,15 +1094,15 @@ describe('outputSchema validation', () => {
  server.setRequestHandler(CallToolRequestSchema, async (request) => {
  if (request.params.name === 'complex-tool') {
  return {
- structuredContent: JSON.stringify({
+ structuredContent: {
  name: 'John Doe',
  age: 30,
  active: true,
  tags: ['user', 'admin'],
  metadata: {
  created: '2023-01-01T00:00:00Z',
  },
- }),
+ },
  };
  }
  throw new Error('Unknown tool');
@@ -1126,9 +1126,9 @@ describe('outputSchema validation', () => {
  // Call the tool - should validate successfully
  const result = await client.callTool({ name: 'complex-tool' });
  expect(result.structuredContent).toBeDefined();
- const parsedContent = JSON.parse(result.structuredContent as string);
- expect(parsedContent.name).toBe('John Doe');
- expect(parsedContent.age).toBe(30);
+ const structuredContent = result.structuredContent as { name: string; age: number };
+ expect(structuredContent.name).toBe('John Doe');
+ expect(structuredContent.age).toBe(30);
  });
 
  test('should fail validation with additional properties when not allowed', async () => {
@@ -1176,10 +1176,10 @@ describe('outputSchema validation', () => {
  if (request.params.name === 'strict-tool') {
  // Return structured content with extra property
  return {
- structuredContent: JSON.stringify({
+ structuredContent: {
  name: 'John',
  extraField: 'not allowed',
- }),
+ },
  };
  }
  throw new Error('Unknown tool');
@@ -1205,4 +1205,137 @@ describe('outputSchema validation', () => {
  /Structured content does not match the tool's output schema/
  );
  });
+
+ test('should throw error when tool without outputSchema returns structuredContent', async () => {
+ const server = new Server({
+ name: 'test-server',
+ version: '1.0.0',
+ }, {
+ capabilities: {
+ tools: {},
+ },
+ });
+
+ // Set up server handlers
+ server.setRequestHandler(InitializeRequestSchema, async (request) => ({
+ protocolVersion: request.params.protocolVersion,
+ capabilities: {},
+ serverInfo: {
+ name: 'test-server',
+ version: '1.0.0',
+ }
+ }));
+
+ server.setRequestHandler(ListToolsRequestSchema, async () => ({
+ tools: [
+ {
+ name: 'test-tool',
+ description: 'A test tool',
+ inputSchema: {
+ type: 'object',
+ properties: {},
+ },
+ // No outputSchema defined
+ },
+ ],
+ }));
+
+ server.setRequestHandler(CallToolRequestSchema, async (request) => {
+ if (request.params.name === 'test-tool') {
+ // Incorrectly return structuredContent for a tool without outputSchema
+ return {
+ structuredContent: { result: 'This should not be allowed' },
+ };
+ }
+ throw new Error('Unknown tool');
+ });
+
+ const client = new Client({
+ name: 'test-client',
+ version: '1.0.0',
+ });
+
+ const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+
+ await Promise.all([
+ client.connect(clientTransport),
+ server.connect(serverTransport),
+ ]);
+
+ // List tools to cache the schemas
+ await client.listTools();
+
+ // Call the tool - should throw validation error
+ await expect(client.callTool({ name: 'test-tool' })).rejects.toThrow(
+ /Tool without outputSchema cannot return structuredContent/
+ );
+ });
+
+ test('should throw error when structuredContent is not an object', async () => {
+ const server = new Server({
+ name: 'test-server',
+ version: '1.0.0',
+ }, {
+ capabilities: {
+ tools: {},
+ },
+ });
+
+ // Set up server handlers
+ server.setRequestHandler(InitializeRequestSchema, async (request) => ({
+ protocolVersion: request.params.protocolVersion,
+ capabilities: {},
+ serverInfo: {
+ name: 'test-server',
+ version: '1.0.0',
+ }
+ }));
+
+ server.setRequestHandler(ListToolsRequestSchema, async () => ({
+ tools: [
+ {
+ name: 'test-tool',
+ description: 'A test tool',
+ inputSchema: {
+ type: 'object',
+ properties: {},
+ },
+ outputSchema: {
+ type: 'object',
+ properties: {
+ result: { type: 'string' },
+ },
+ },
+ },
+ ],
+ }));
+
+ server.setRequestHandler(CallToolRequestSchema, async (request) => {
+ if (request.params.name === 'test-tool') {
+ // Try to return a non-object value as structuredContent
+ return {
+ structuredContent: "This should be an object, not a string" as any,
+ };
+ }
+ throw new Error('Unknown tool');
+ });
+
+ const client = new Client({
+ name: 'test-client',
+ version: '1.0.0',
+ });
+
+ const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+
+ await Promise.all([
+ client.connect(clientTransport),
+ server.connect(serverTransport),
+ ]);
+
+ // List tools to cache the schemas
+ await client.listTools();
+
+ // Call the tool - should throw validation error
+ await expect(client.callTool({ name: 'test-tool' })).rejects.toThrow();
+ });
 });

src/client/index.ts

@@ -438,11 +438,8 @@ export class Client<
  }
 
  try {
- // Parse the structured content as JSON
- const contentData = JSON.parse(result.structuredContent as string);
- 
- // Validate the content against the schema
- const validationResult = outputSchema.safeParse(contentData);
+ // Validate the structured content (which is already an object) against the schema
+ const validationResult = outputSchema.safeParse(result.structuredContent);
 
  if (!validationResult.success) {
  throw new McpError(
@@ -459,6 +456,14 @@ export class Client<
  `Failed to validate structured content: ${error instanceof Error ? error.message : String(error)}`
  );
  }
+ } else {
+ // If tool doesn't have outputSchema, it MUST NOT return structuredContent
+ if (result.structuredContent) {
+ throw new McpError(
+ ErrorCode.InvalidRequest,
+ `Tool without outputSchema cannot return structuredContent`
+ );
+ }
  }
 
  return result;

src/server/mcp.test.ts

@@ -795,11 +795,11 @@ describe("tool()", () => {
  },
  async ({ input }) => ({
  // When outputSchema is defined, return structuredContent instead of content
- structuredContent: JSON.stringify({
+ structuredContent: {
  processedInput: input,
  resultType: "structured",
  timestamp: "2023-01-01T00:00:00Z"
- }),
+ },
  }),
  );
 
@@ -860,10 +860,14 @@ describe("tool()", () => {
  expect(result.structuredContent).toBeDefined();
  expect(result.content).toBeUndefined(); // Should not have content when structuredContent is used
 
- const parsed = JSON.parse(result.structuredContent || "{}");
- expect(parsed.processedInput).toBe("hello");
- expect(parsed.resultType).toBe("structured");
- expect(parsed.timestamp).toBe("2023-01-01T00:00:00Z");
+ const structuredContent = result.structuredContent as { 
+ processedInput: string;
+ resultType: string;
+ timestamp: string;
+ };
+ expect(structuredContent.processedInput).toBe("hello");
+ expect(structuredContent.resultType).toBe("structured");
+ expect(structuredContent.timestamp).toBe("2023-01-01T00:00:00Z");
  });
 
  test("should pass sessionId to tool callback via RequestHandlerExtra", async () => {

src/types.test.ts

@@ -4,7 +4,7 @@ describe("Types", () => {
 
  test("should have correct latest protocol version", () => {
  expect(LATEST_PROTOCOL_VERSION).toBeDefined();
- expect(LATEST_PROTOCOL_VERSION).toBe("2025-03-26");
+ expect(LATEST_PROTOCOL_VERSION).toBe("DRAFT-2025-v2");
  });
  test("should have correct supported protocol versions", () => {
  expect(SUPPORTED_PROTOCOL_VERSIONS).toBeDefined();