docs(agents-core): document MCP structuredContent; test(mcp): add structured content tests and update stubs; chore(changeset): minor bump

Author: SkinnnyJay

.changeset/mcp-structured-content.md

@@ -0,0 +1,14 @@
+---
+'@openai/agents-core': minor
+---
+
+feat(mcp): add structuredContent support behind `useStructuredContent`; return full CallToolResult from `callTool`
+
+- `MCPServer#callTool` now returns the full `CallToolResult` (was `content[]`), exposing optional `structuredContent`.
+- Add `useStructuredContent` option to MCP servers (stdio/streamable-http/SSE), default `false` to avoid duplicate data by default.
+- When enabled, function tool outputs include `structuredContent` (or return it alone when no `content`).
+
+Notes
+
+- Type-only breaking change for direct `callTool` consumers: use `result.content` where arrays were expected.
+- Behavior matches Python SDK feature (openai-agents-python#1150) while keeping JS outputs ergonomic (objects/arrays, no JSON stringify/parse overhead).

packages/agents-core/test/mcpStructuredContent.test.ts

@@ -64,12 +64,12 @@ describe('MCP structuredContent handling', () => {
       false,
     );
 
-    const out = await tool.invoke({} as any, {});
+    const out = await tool.invoke({} as any, '{}');
     // when not using structured content, return the single content object
     expect(out).toEqual({ type: 'text', text: 'hello' });
   });
 
-  it('includes structuredContent when enabled: single content -> newline-concatenated string', async () => {
+  it('includes structuredContent when enabled: single content -> array with structuredContent appended', async () => {
     const server = new StubServer(
       's',
       [
@@ -106,8 +106,8 @@ describe('MCP structuredContent handling', () => {
       false,
     );
 
-    const out = await tool.invoke({} as any, {});
-    expect(out).toBe('{"type":"text","text":"hello"}\n{"foo":1}');
+    const out = await tool.invoke({} as any, '{}');
+    expect(out).toEqual([{ type: 'text', text: 'hello' }, { foo: 1 }]);
   });
 
   it('includes structuredContent when enabled: no content -> structuredContent only', async () => {
@@ -147,7 +147,7 @@ describe('MCP structuredContent handling', () => {
       false,
     );
 
-    const out = await tool.invoke({} as any, {});
+    const out = await tool.invoke({} as any, '{}');
     expect(out).toEqual({ foo: 1 });
   });
 
@@ -191,7 +191,7 @@ describe('MCP structuredContent handling', () => {
       false,
     );
 
-    const out = await tool.invoke({} as any, {});
+    const out = await tool.invoke({} as any, '{}');
     expect(out).toEqual([
       { type: 'text', text: 'a' },
       { type: 'text', text: 'b' },

packages/agents-core/test/mcpToolFilter.integration.test.ts

@@ -60,23 +60,25 @@ class StubFilesystemServer extends NodeMCPServerStdio {
   async callTool(name: string, args: any) {
     const blocked = (this.toolFilter as any)?.blockedToolNames ?? [];
     if (blocked.includes(name)) {
-      return [
-        { type: 'text', text: `Tool "${name}" is blocked by MCP filter` },
-      ];
+      return {
+        content: [
+          { type: 'text', text: `Tool "${name}" is blocked by MCP filter` },
+        ],
+      } as any;
     }
     if (name === 'list_directory') {
       const files = fs.readdirSync(this.dir);
-      return [{ type: 'text', text: files.join('\n') }];
+      return { content: [{ type: 'text', text: files.join('\n') }] } as any;
     }
     if (name === 'read_file') {
       const text = fs.readFileSync(path.join(this.dir, args.path), 'utf8');
-      return [{ type: 'text', text }];
+      return { content: [{ type: 'text', text }] } as any;
     }
     if (name === 'write_file') {
       fs.writeFileSync(path.join(this.dir, args.path), args.text, 'utf8');
-      return [{ type: 'text', text: 'ok' }];
+      return { content: [{ type: 'text', text: 'ok' }] } as any;
     }
-    return [];
+    return { content: [] } as any;
   }
 }