@tryfinch/finch-api-mcp 6.30.0 → 7.0.0

package/src/docs-search-tool.ts

@@ -0,0 +1,59 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { Metadata, asTextContentResult } from './tools/types';
+
+import { Tool } from '@modelcontextprotocol/sdk/types.js';
+
+export const metadata: Metadata = {
+  resource: 'all',
+  operation: 'read',
+  tags: [],
+  httpMethod: 'get',
+};
+
+export const tool: Tool = {
+  name: 'search_docs',
+  description: 'Search for documentation for how to use the client to interact with the API.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      query: {
+        type: 'string',
+        description: 'The query to search for.',
+      },
+      language: {
+        type: 'string',
+        description: 'The language for the SDK to search for.',
+        enum: ['http', 'python', 'go', 'typescript', 'javascript', 'terraform', 'ruby', 'java', 'kotlin'],
+      },
+      detail: {
+        type: 'string',
+        description: 'The amount of detail to return.',
+        enum: ['default', 'verbose'],
+      },
+    },
+    required: ['query', 'language'],
+  },
+  annotations: {
+    readOnlyHint: true,
+  },
+};
+
+const docsSearchURL =
+  process.env['DOCS_SEARCH_URL'] || 'https://api.stainless.com/api/projects/finch/docs/search';
+
+export const handler = async (_: unknown, args: Record<string, unknown> | undefined) => {
+  const body = args as any;
+  const query = new URLSearchParams(body).toString();
+  const result = await fetch(`${docsSearchURL}?${query}`);
+
+  if (!result.ok) {
+    throw new Error(
+      `${result.status}: ${result.statusText} when using doc search tool. Details: ${await result.text()}`,
+    );
+  }
+
+  return asTextContentResult(await result.json());
+};
+
+export default { metadata, tool, handler };

package/src/dynamic-tools.ts

@@ -1,5 +1,5 @@
 import Finch from '@tryfinch/finch-api';
-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';
@@ -14,7 +14,7 @@ function zodToInputSchema(schema: z.ZodSchema) {
 /**
  * A list of tools that expose all the endpoints in the API dynamically.
  *
- * Instead of exposing every endpoint as it's own tool, which uses up too many tokens for LLMs to use at once,
+ * Instead of exposing every endpoint as its own tool, which uses up too many tokens for LLMs to use at once,
  * we expose a single tool that can be used to search for endpoints by name, resource, operation, or tag, and then
  * a generic endpoint that can be used to invoke any endpoint with the provided arguments.
  *
@@ -38,10 +38,10 @@ export function dynamicTools(endpoints: Endpoint[]): Endpoint[] {
     },
     tool: {
       name: 'list_api_endpoints',
-      description: 'List or search for all endpoints in the Finch Node API',
+      description: 'List or search for all endpoints in the Finch TypeScript API',
       inputSchema: zodToInputSchema(listEndpointsSchema),
     },
-    handler: async (client: Finch, args: Record<string, unknown> | undefined) => {
+    handler: async (client: Finch, args: Record<string, unknown> | undefined): Promise<ToolCallResult> => {
       const query = args && listEndpointsSchema.parse(args).search_query?.trim();
 
       const filteredEndpoints =
@@ -49,15 +49,16 @@ export function dynamicTools(endpoints: Endpoint[]): Endpoint[] {
           endpoints.filter((endpoint) => {
             const fieldsToMatch = [
               endpoint.tool.name,
+              endpoint.tool.description,
               endpoint.metadata.resource,
               endpoint.metadata.operation,
               ...endpoint.metadata.tags,
             ];
-            return fieldsToMatch.some((field) => field.toLowerCase().includes(query.toLowerCase()));
+            return fieldsToMatch.some((field) => field && field.toLowerCase().includes(query.toLowerCase()));
           })
         : endpoints;
 
-      return {
+      return asTextContentResult({
         tools: filteredEndpoints.map(({ tool, metadata }) => ({
           name: tool.name,
           description: tool.description,
@@ -65,7 +66,7 @@ export function dynamicTools(endpoints: Endpoint[]): Endpoint[] {
           operation: metadata.operation,
           tags: metadata.tags,
         })),
-      };
+      });
     },
   };
 
@@ -81,7 +82,7 @@ export function dynamicTools(endpoints: Endpoint[]): Endpoint[] {
     tool: {
       name: 'get_api_endpoint_schema',
       description:
-        'Get the schema for an endpoint in the Finch Node API. You can use the schema returned by this tool to invoke an endpoint with the `invoke_api_endpoint` tool.',
+        'Get the schema for an endpoint in the Finch TypeScript API. You can use the schema returned by this tool to invoke an endpoint with the `invoke_api_endpoint` tool.',
       inputSchema: zodToInputSchema(getEndpointSchema),
     },
     handler: async (client: Finch, args: Record<string, unknown> | undefined) => {
@@ -94,7 +95,7 @@ export function dynamicTools(endpoints: Endpoint[]): Endpoint[] {
       if (!endpoint) {
         throw new Error(`Endpoint ${endpointName} not found`);
       }
-      return endpoint.tool;
+      return asTextContentResult(endpoint.tool);
     },
   };
 
@@ -116,10 +117,10 @@ export function dynamicTools(endpoints: Endpoint[]): Endpoint[] {
     tool: {
       name: 'invoke_api_endpoint',
       description:
-        'Invoke an endpoint in the Finch Node 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.',
+        'Invoke an endpoint in the Finch 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: Finch, args: Record<string, unknown> | undefined) => {
+    handler: async (client: Finch, args: Record<string, unknown> | undefined): Promise<ToolCallResult> => {
       if (!args) {
         throw new Error('No endpoint provided');
       }
@@ -144,7 +145,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);
     },
   };
 

package/src/filtering.ts

@@ -0,0 +1,18 @@
+// @ts-nocheck
+import initJq from 'jq-web';
+
+export async function maybeFilter(jqFilter: unknown | undefined, response: any): Promise<any> {
+  if (jqFilter && typeof jqFilter === 'string') {
+    return await jq(response, jqFilter);
+  } else {
+    return response;
+  }
+}
+
+async function jq(json: any, jqFilter: string) {
+  return (await initJq).json(json, jqFilter);
+}
+
+export function isJqError(error: any): error is Error {
+  return error instanceof Error && 'stderr' in error;
+}

package/src/headers.ts

@@ -0,0 +1,35 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { IncomingMessage } from 'node:http';
+import { ClientOptions } from '@tryfinch/finch-api';
+
+export const parseAuthHeaders = (req: IncomingMessage): Partial<ClientOptions> => {
+  if (req.headers.authorization) {
+    const scheme = req.headers.authorization.split(' ')[0]!;
+    const value = req.headers.authorization.slice(scheme.length + 1);
+    switch (scheme) {
+      case 'Bearer':
+        return { accessToken: req.headers.authorization.slice('Bearer '.length) };
+      case 'Basic':
+        const rawValue = Buffer.from(value, 'base64').toString();
+        return {
+          clientID: rawValue.slice(0, rawValue.search(':')),
+          clientSecret: rawValue.slice(rawValue.search(':') + 1),
+        };
+      default:
+        throw new Error(
+          'Unsupported authorization scheme. Expected the "Authorization" header to be a supported scheme (Bearer, Basic).',
+        );
+    }
+  }
+
+  const clientID =
+    Array.isArray(req.headers['x-finch-client-id']) ?
+      req.headers['x-finch-client-id'][0]
+    : req.headers['x-finch-client-id'];
+  const clientSecret =
+    Array.isArray(req.headers['x-finch-client-secret']) ?
+      req.headers['x-finch-client-secret'][0]
+    : req.headers['x-finch-client-secret'];
+  return { clientID, clientSecret };
+};

package/src/http.ts

@@ -0,0 +1,127 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+
+import express from 'express';
+import { fromError } from 'zod-validation-error/v3';
+import { McpOptions, parseQueryOptions } from './options';
+import { ClientOptions, initMcpServer, newMcpServer } from './server';
+import { parseAuthHeaders } from './headers';
+
+const newServer = ({
+  clientOptions,
+  mcpOptions: defaultMcpOptions,
+  req,
+  res,
+}: {
+  clientOptions: ClientOptions;
+  mcpOptions: McpOptions;
+  req: express.Request;
+  res: express.Response;
+}): McpServer | null => {
+  const server = newMcpServer();
+
+  let mcpOptions: McpOptions;
+  try {
+    mcpOptions = parseQueryOptions(defaultMcpOptions, req.query);
+  } catch (error) {
+    res.status(400).json({
+      jsonrpc: '2.0',
+      error: {
+        code: -32000,
+        message: `Invalid request: ${fromError(error)}`,
+      },
+    });
+    return null;
+  }
+
+  try {
+    const authOptions = parseAuthHeaders(req);
+    initMcpServer({
+      server: server,
+      clientOptions: {
+        ...clientOptions,
+        ...authOptions,
+      },
+      mcpOptions,
+    });
+  } catch (error) {
+    res.status(401).json({
+      jsonrpc: '2.0',
+      error: {
+        code: -32000,
+        message: `Unauthorized: ${error instanceof Error ? error.message : error}`,
+      },
+    });
+    return null;
+  }
+
+  return server;
+};
+
+const post =
+  (options: { clientOptions: ClientOptions; mcpOptions: McpOptions }) =>
+  async (req: express.Request, res: express.Response) => {
+    const server = newServer({ ...options, req, res });
+    // If we return null, we already set the authorization error.
+    if (server === null) return;
+    const transport = new StreamableHTTPServerTransport({
+      // Stateless server
+      sessionIdGenerator: undefined,
+    });
+    await server.connect(transport);
+    await transport.handleRequest(req, res, req.body);
+  };
+
+const get = async (req: express.Request, res: express.Response) => {
+  res.status(405).json({
+    jsonrpc: '2.0',
+    error: {
+      code: -32000,
+      message: 'Method not supported',
+    },
+  });
+};
+
+const del = async (req: express.Request, res: express.Response) => {
+  res.status(405).json({
+    jsonrpc: '2.0',
+    error: {
+      code: -32000,
+      message: 'Method not supported',
+    },
+  });
+};
+
+export const streamableHTTPApp = ({
+  clientOptions = {},
+  mcpOptions = {},
+}: {
+  clientOptions?: ClientOptions;
+  mcpOptions?: McpOptions;
+}): express.Express => {
+  const app = express();
+  app.set('query parser', 'extended');
+  app.use(express.json());
+
+  app.get('/', get);
+  app.post('/', post({ clientOptions, mcpOptions }));
+  app.delete('/', del);
+
+  return app;
+};
+
+export const launchStreamableHTTPServer = async (options: McpOptions, port: number | string | undefined) => {
+  const app = streamableHTTPApp({ mcpOptions: options });
+  const server = app.listen(port);
+  const address = server.address();
+
+  if (typeof address === 'string') {
+    console.error(`MCP Server running on streamable HTTP at ${address}`);
+  } else if (address !== null) {
+    console.error(`MCP Server running on streamable HTTP on port ${address.port}`);
+  } else {
+    console.error(`MCP Server running on streamable HTTP on port ${port}`);
+  }
+};

package/src/index.ts

@@ -1,7 +1,10 @@
-import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { init, selectTools, server } from './server';
+#!/usr/bin/env node
+
+import { selectTools } from './server';
 import { Endpoint, endpoints } from './tools';
-import { ParsedOptions, parseOptions } from './options';
+import { McpOptions, parseCLIOptions } from './options';
+import { launchStdioServer } from './stdio';
+import { launchStreamableHTTPServer } from './http';
 
 async function main() {
   const options = parseOptionsOrError();
@@ -11,18 +14,21 @@ async function main() {
     return;
   }
 
-  const includedTools = selectToolsOrError(endpoints, options);
+  const selectedTools = await selectToolsOrError(endpoints, options);
 
   console.error(
-    `MCP Server starting with ${includedTools.length} tools:`,
-    includedTools.map((e) => e.tool.name),
+    `MCP Server starting with ${selectedTools.length} tools:`,
+    selectedTools.map((e) => e.tool.name),
   );
 
-  init({ server, endpoints: includedTools });
-
-  const transport = new StdioServerTransport();
-  await server.connect(transport);
-  console.error('MCP Server running on stdio');
+  switch (options.transport) {
+    case 'stdio':
+      await launchStdioServer(options);
+      break;
+    case 'http':
+      await launchStreamableHTTPServer(options, options.port ?? options.socket);
+      break;
+  }
 }
 
 if (require.main === module) {
@@ -34,16 +40,16 @@ if (require.main === module) {
 
 function parseOptionsOrError() {
   try {
-    return parseOptions();
+    return parseCLIOptions();
   } catch (error) {
     console.error('Error parsing options:', error);
     process.exit(1);
   }
 }
 
-function selectToolsOrError(endpoints: Endpoint[], options: ParsedOptions) {
+async function selectToolsOrError(endpoints: Endpoint[], options: McpOptions): Promise<Endpoint[]> {
   try {
-    const includedTools = selectTools(endpoints, options);
+    const includedTools = await selectTools(endpoints, options);
     if (includedTools.length === 0) {
       console.error('No tools match the provided filters.');
       process.exit(1);