feat(mcp): implement support for binary responses

stainless-app[bot] · stainless-app[bot] · commit a89234fd6eb4 · 2025-06-06T03:45:51.000Z
diff --git a/packages/mcp-server/src/dynamic-tools.ts b/packages/mcp-server/src/dynamic-tools.ts
@@ -1,5 +1,5 @@
 import ScanDocuments from 'scan-documents';
-import { Endpoint } from './tools';
+import { Endpoint, asTextContentResult, ToolCallResult } from './tools/types';
 import { zodToJsonSchema } from 'zod-to-json-schema';
 import { z } from 'zod';
 import { Cabidela } from '@cloudflare/cabidela';
@@ -41,7 +41,10 @@ export function dynamicTools(endpoints: Endpoint[]): Endpoint[] {
       description: 'List or search for all endpoints in the Scan Documents TypeScript API',
       inputSchema: zodToInputSchema(listEndpointsSchema),
     },
-    handler: async (client: ScanDocuments, args: Record<string, unknown> | undefined) => {
+    handler: async (
+      client: ScanDocuments,
+      args: Record<string, unknown> | undefined,
+    ): Promise<ToolCallResult> => {
       const query = args && listEndpointsSchema.parse(args).search_query?.trim();
 
       const filteredEndpoints =
@@ -58,15 +61,15 @@ export function dynamicTools(endpoints: Endpoint[]): Endpoint[] {
           })
         : endpoints;
 
-      return {
+      return asTextContentResult({
         tools: filteredEndpoints.map(({ tool, metadata }) => ({
           name: tool.name,
           description: tool.description,
           resource: metadata.resource,
           operation: metadata.operation,
           tags: metadata.tags,
         })),
-      };
+      });
     },
   };
 
@@ -95,7 +98,7 @@ export function dynamicTools(endpoints: Endpoint[]): Endpoint[] {
       if (!endpoint) {
         throw new Error(`Endpoint ${endpointName} not found`);
       }
-      return endpoint.tool;
+      return asTextContentResult(endpoint.tool);
     },
   };
 
@@ -120,7 +123,10 @@ export function dynamicTools(endpoints: Endpoint[]): Endpoint[] {
         'Invoke an endpoint in the Scan Documents TypeScript API. Note: use the `list_api_endpoints` tool to get the list of endpoints and `get_api_endpoint_schema` tool to get the schema for an endpoint.',
       inputSchema: zodToInputSchema(invokeEndpointSchema),
     },
-    handler: async (client: ScanDocuments, args: Record<string, unknown> | undefined) => {
+    handler: async (
+      client: ScanDocuments,
+      args: Record<string, unknown> | undefined,
+    ): Promise<ToolCallResult> => {
       if (!args) {
         throw new Error('No endpoint provided');
       }
@@ -145,7 +151,7 @@ export function dynamicTools(endpoints: Endpoint[]): Endpoint[] {
         throw new Error(`Invalid arguments for endpoint ${endpoint_name}:\n${error}`);
       }
 
-      return endpoint.handler(client, endpointArgs);
+      return await endpoint.handler(client, endpointArgs);
     },
   };
 
diff --git a/packages/mcp-server/src/server.ts b/packages/mcp-server/src/server.ts
@@ -99,15 +99,7 @@ export async function executeHandler(
   if (options.validJson && args) {
     args = parseEmbeddedJSON(args, tool.inputSchema);
   }
-  const result = await handler(client, args || {});
-  return {
-    content: [
-      {
-        type: 'text',
-        text: JSON.stringify(result, null, 2),
-      },
-    ],
-  };
+  return await handler(client, args || {});
 }
 
 export const readEnv = (env: string): string | undefined => {
diff --git a/packages/mcp-server/src/tools/events/list-events.ts b/packages/mcp-server/src/tools/events/list-events.ts
@@ -1,5 +1,7 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
+import { asTextContentResult } from 'scan-documents-mcp/tools/types';
+
 import { Tool } from '@modelcontextprotocol/sdk/types.js';
 import type { Metadata } from '../';
 import ScanDocuments from 'scan-documents';
@@ -29,9 +31,9 @@ export const tool: Tool = {
   },
 };
 
-export const handler = (client: ScanDocuments, args: Record<string, unknown> | undefined) => {
+export const handler = async (client: ScanDocuments, args: Record<string, unknown> | undefined) => {
   const body = args as any;
-  return client.events.list(body);
+  return asTextContentResult(await client.events.list(body));
 };
 
 export default { metadata, tool, handler };
diff --git a/packages/mcp-server/src/tools/files/delete-files.ts b/packages/mcp-server/src/tools/files/delete-files.ts
@@ -1,5 +1,7 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
+import { asTextContentResult } from 'scan-documents-mcp/tools/types';
+
 import { Tool } from '@modelcontextprotocol/sdk/types.js';
 import type { Metadata } from '../';
 import ScanDocuments from 'scan-documents';
@@ -26,9 +28,10 @@ export const tool: Tool = {
   },
 };
 
-export const handler = (client: ScanDocuments, args: Record<string, unknown> | undefined) => {
+export const handler = async (client: ScanDocuments, args: Record<string, unknown> | undefined) => {
   const { id, ...body } = args as any;
-  return client.files.delete(id);
+  await client.files.delete(id);
+  return asTextContentResult('Successful tool call');
 };
 
 export default { metadata, tool, handler };
diff --git a/packages/mcp-server/src/tools/files/download-files.ts b/packages/mcp-server/src/tools/files/download-files.ts
@@ -1,5 +1,7 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
+import { asBinaryContentResult } from 'scan-documents-mcp/tools/types';
+
 import { Tool } from '@modelcontextprotocol/sdk/types.js';
 import type { Metadata } from '../';
 import ScanDocuments from 'scan-documents';
@@ -26,9 +28,9 @@ export const tool: Tool = {
   },
 };
 
-export const handler = (client: ScanDocuments, args: Record<string, unknown> | undefined) => {
+export const handler = async (client: ScanDocuments, args: Record<string, unknown> | undefined) => {
   const { id, ...body } = args as any;
-  return client.files.download(id);
+  return asBinaryContentResult(await client.files.download(id));
 };
 
 export default { metadata, tool, handler };
diff --git a/packages/mcp-server/src/tools/files/list-files.ts b/packages/mcp-server/src/tools/files/list-files.ts
@@ -1,5 +1,7 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
+import { asTextContentResult } from 'scan-documents-mcp/tools/types';
+
 import { Tool } from '@modelcontextprotocol/sdk/types.js';
 import type { Metadata } from '../';
 import ScanDocuments from 'scan-documents';
@@ -31,9 +33,9 @@ export const tool: Tool = {
   },
 };
 
-export const handler = (client: ScanDocuments, args: Record<string, unknown> | undefined) => {
+export const handler = async (client: ScanDocuments, args: Record<string, unknown> | undefined) => {
   const body = args as any;
-  return client.files.list(body);
+  return asTextContentResult(await client.files.list(body));
 };
 
 export default { metadata, tool, handler };
diff --git a/packages/mcp-server/src/tools/files/retrieve-files.ts b/packages/mcp-server/src/tools/files/retrieve-files.ts
@@ -1,5 +1,7 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
+import { asTextContentResult } from 'scan-documents-mcp/tools/types';
+
 import { Tool } from '@modelcontextprotocol/sdk/types.js';
 import type { Metadata } from '../';
 import ScanDocuments from 'scan-documents';
@@ -26,9 +28,9 @@ export const tool: Tool = {
   },
 };
 
-export const handler = (client: ScanDocuments, args: Record<string, unknown> | undefined) => {
+export const handler = async (client: ScanDocuments, args: Record<string, unknown> | undefined) => {
   const { id, ...body } = args as any;
-  return client.files.retrieve(id);
+  return asTextContentResult(await client.files.retrieve(id));
 };
 
 export default { metadata, tool, handler };
diff --git a/packages/mcp-server/src/tools/files/upload-files.ts b/packages/mcp-server/src/tools/files/upload-files.ts
@@ -1,5 +1,7 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
+import { asTextContentResult } from 'scan-documents-mcp/tools/types';
+
 import { Tool } from '@modelcontextprotocol/sdk/types.js';
 import type { Metadata } from '../';
 import ScanDocuments from 'scan-documents';
@@ -31,9 +33,9 @@ export const tool: Tool = {
   },
 };
 
-export const handler = (client: ScanDocuments, args: Record<string, unknown> | undefined) => {
+export const handler = async (client: ScanDocuments, args: Record<string, unknown> | undefined) => {
   const body = args as any;
-  return client.files.upload(body);
+  return asTextContentResult(await client.files.upload(body));
 };
 
 export default { metadata, tool, handler };
diff --git a/packages/mcp-server/src/tools/image-operations/apply-effect-image-operations.ts b/packages/mcp-server/src/tools/image-operations/apply-effect-image-operations.ts
@@ -1,5 +1,7 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
+import { asTextContentResult } from 'scan-documents-mcp/tools/types';
+
 import { Tool } from '@modelcontextprotocol/sdk/types.js';
 import type { Metadata } from '../';
 import ScanDocuments from 'scan-documents';
@@ -36,9 +38,9 @@ export const tool: Tool = {
   },
 };
 
-export const handler = (client: ScanDocuments, args: Record<string, unknown> | undefined) => {
+export const handler = async (client: ScanDocuments, args: Record<string, unknown> | undefined) => {
   const body = args as any;
-  return client.imageOperations.applyEffect(body);
+  return asTextContentResult(await client.imageOperations.applyEffect(body));
 };
 
 export default { metadata, tool, handler };
diff --git a/packages/mcp-server/src/tools/image-operations/convert-image-operations.ts b/packages/mcp-server/src/tools/image-operations/convert-image-operations.ts
@@ -1,5 +1,7 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
+import { asTextContentResult } from 'scan-documents-mcp/tools/types';
+
 import { Tool } from '@modelcontextprotocol/sdk/types.js';
 import type { Metadata } from '../';
 import ScanDocuments from 'scan-documents';
@@ -85,9 +87,9 @@ export const tool: Tool = {
   },
 };
 
-export const handler = (client: ScanDocuments, args: Record<string, unknown> | undefined) => {
+export const handler = async (client: ScanDocuments, args: Record<string, unknown> | undefined) => {
   const body = args as any;
-  return client.imageOperations.convert(body);
+  return asTextContentResult(await client.imageOperations.convert(body));
 };
 
 export default { metadata, tool, handler };
diff --git a/packages/mcp-server/src/tools/image-operations/detect-documents-image-operations.ts b/packages/mcp-server/src/tools/image-operations/detect-documents-image-operations.ts
@@ -1,5 +1,7 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
+import { asTextContentResult } from 'scan-documents-mcp/tools/types';
+
 import { Tool } from '@modelcontextprotocol/sdk/types.js';
 import type { Metadata } from '../';
 import ScanDocuments from 'scan-documents';
@@ -27,9 +29,9 @@ export const tool: Tool = {
   },
 };
 
-export const handler = (client: ScanDocuments, args: Record<string, unknown> | undefined) => {
+export const handler = async (client: ScanDocuments, args: Record<string, unknown> | undefined) => {
   const body = args as any;
-  return client.imageOperations.detectDocuments(body);
+  return asTextContentResult(await client.imageOperations.detectDocuments(body));
 };
 
 export default { metadata, tool, handler };
diff --git a/packages/mcp-server/src/tools/image-operations/extract-text-image-operations.ts b/packages/mcp-server/src/tools/image-operations/extract-text-image-operations.ts
@@ -1,5 +1,7 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
+import { asTextContentResult } from 'scan-documents-mcp/tools/types';
+
 import { Tool } from '@modelcontextprotocol/sdk/types.js';
 import type { Metadata } from '../';
 import ScanDocuments from 'scan-documents';
@@ -117,9 +119,9 @@ export const tool: Tool = {
   },
 };
 
-export const handler = (client: ScanDocuments, args: Record<string, unknown> | undefined) => {
+export const handler = async (client: ScanDocuments, args: Record<string, unknown> | undefined) => {
   const body = args as any;
-  return client.imageOperations.extractText(body);
+  return asTextContentResult(await client.imageOperations.extractText(body));
 };
 
 export default { metadata, tool, handler };
diff --git a/packages/mcp-server/src/tools/image-operations/warp-image-operations.ts b/packages/mcp-server/src/tools/image-operations/warp-image-operations.ts
@@ -1,5 +1,7 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
+import { asTextContentResult } from 'scan-documents-mcp/tools/types';
+
 import { Tool } from '@modelcontextprotocol/sdk/types.js';
 import type { Metadata } from '../';
 import ScanDocuments from 'scan-documents';
@@ -39,9 +41,9 @@ export const tool: Tool = {
   },
 };
 
-export const handler = (client: ScanDocuments, args: Record<string, unknown> | undefined) => {
+export const handler = async (client: ScanDocuments, args: Record<string, unknown> | undefined) => {
   const body = args as any;
-  return client.imageOperations.warp(body);
+  return asTextContentResult(await client.imageOperations.warp(body));
 };
 
 export default { metadata, tool, handler };
diff --git a/packages/mcp-server/src/tools/index.ts b/packages/mcp-server/src/tools/index.ts
@@ -1,7 +1,8 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
-import ScanDocuments from 'scan-documents';
-import { Tool } from '@modelcontextprotocol/sdk/types.js';
+import { Metadata, Endpoint, HandlerFunction } from './types';
+
+export { Metadata, Endpoint, HandlerFunction };
 
 import retrieve_files from './files/retrieve-files';
 import list_files from './files/list-files';
@@ -21,27 +22,6 @@ import merge_pdf_operations from './pdf-operations/merge-pdf-operations';
 import render_pdf_operations from './pdf-operations/render-pdf-operations';
 import split_pdf_operations from './pdf-operations/split-pdf-operations';
 
-export type HandlerFunction = (
-  client: ScanDocuments,
-  args: Record<string, unknown> | undefined,
-) => Promise<any>;
-
-export type Metadata = {
-  resource: string;
-  operation: 'read' | 'write';
-  tags: string[];
-
-  httpMethod?: string;
-  httpPath?: string;
-  operationId?: string;
-};
-
-export type Endpoint = {
-  metadata: Metadata;
-  tool: Tool;
-  handler: HandlerFunction;
-};
-
 export const endpoints: Endpoint[] = [];
 
 function addEndpoint(endpoint: Endpoint) {
diff --git a/packages/mcp-server/src/tools/pdf-operations/extract-pages-pdf-operations.ts b/packages/mcp-server/src/tools/pdf-operations/extract-pages-pdf-operations.ts
@@ -1,5 +1,7 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
+import { asTextContentResult } from 'scan-documents-mcp/tools/types';
+
 import { Tool } from '@modelcontextprotocol/sdk/types.js';
 import type { Metadata } from '../';
 import ScanDocuments from 'scan-documents';
@@ -35,9 +37,9 @@ export const tool: Tool = {
   },
 };
 
-export const handler = (client: ScanDocuments, args: Record<string, unknown> | undefined) => {
+export const handler = async (client: ScanDocuments, args: Record<string, unknown> | undefined) => {
   const body = args as any;
-  return client.pdfOperations.extractPages(body);
+  return asTextContentResult(await client.pdfOperations.extractPages(body));
 };
 
 export default { metadata, tool, handler };
diff --git a/packages/mcp-server/src/tools/pdf-operations/merge-pdf-operations.ts b/packages/mcp-server/src/tools/pdf-operations/merge-pdf-operations.ts
@@ -1,5 +1,7 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
+import { asTextContentResult } from 'scan-documents-mcp/tools/types';
+
 import { Tool } from '@modelcontextprotocol/sdk/types.js';
 import type { Metadata } from '../';
 import ScanDocuments from 'scan-documents';
@@ -35,9 +37,9 @@ export const tool: Tool = {
   },
 };
 
-export const handler = (client: ScanDocuments, args: Record<string, unknown> | undefined) => {
+export const handler = async (client: ScanDocuments, args: Record<string, unknown> | undefined) => {
   const body = args as any;
-  return client.pdfOperations.merge(body);
+  return asTextContentResult(await client.pdfOperations.merge(body));
 };
 
 export default { metadata, tool, handler };
diff --git a/packages/mcp-server/src/tools/pdf-operations/render-pdf-operations.ts b/packages/mcp-server/src/tools/pdf-operations/render-pdf-operations.ts
diff --git a/packages/mcp-server/src/tools/pdf-operations/split-pdf-operations.ts b/packages/mcp-server/src/tools/pdf-operations/split-pdf-operations.ts
diff --git a/packages/mcp-server/src/tools/tasks/list-tasks.ts b/packages/mcp-server/src/tools/tasks/list-tasks.ts
diff --git a/packages/mcp-server/src/tools/tasks/retrieve-tasks.ts b/packages/mcp-server/src/tools/tasks/retrieve-tasks.ts
diff --git a/packages/mcp-server/src/tools/types.ts b/packages/mcp-server/src/tools/types.ts
diff --git a/packages/mcp-server/tests/dynamic-tools.test.ts b/packages/mcp-server/tests/dynamic-tools.test.ts
