@roarkanalytics/sdk-mcp 2.19.1 → 2.23.0

package/src/code-tool.ts

@@ -1,10 +1,17 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
-import { McpTool, Metadata, ToolCallResult, asErrorResult, asTextContentResult } from './types';
+import {
+  McpRequestContext,
+  McpTool,
+  Metadata,
+  ToolCallResult,
+  asErrorResult,
+  asTextContentResult,
+} from './types';
 import { Tool } from '@modelcontextprotocol/sdk/types.js';
-import { readEnv, requireValue } from './server';
+import { readEnv, requireValue } from './util';
 import { WorkerInput, WorkerOutput } from './code-tool-types';
-import { Roark } from '@roarkanalytics/sdk';
+import { SdkMethod } from './methods';
 
 const prompt = `Runs JavaScript code to interact with the Roark API.
 
@@ -35,7 +42,7 @@ Variables will not persist between calls, so make sure to return or log any data
  *
  * @param endpoints - The endpoints to include in the list.
  */
-export function codeTool(): McpTool {
+export function codeTool({ blockedMethods }: { blockedMethods: SdkMethod[] | undefined }): McpTool {
   const metadata: Metadata = { resource: 'all', operation: 'write', tags: [] };
   const tool: Tool = {
     name: 'execute',
@@ -55,20 +62,41 @@ export function codeTool(): McpTool {
       required: ['code'],
     },
   };
-  const handler = async (client: Roark, args: any): Promise<ToolCallResult> => {
+  const handler = async ({
+    reqContext,
+    args,
+  }: {
+    reqContext: McpRequestContext;
+    args: any;
+  }): Promise<ToolCallResult> => {
     const code = args.code as string;
     const intent = args.intent as string | undefined;
+    const client = reqContext.client;
+
+    // Do very basic blocking of code that includes forbidden method names.
+    //
+    // WARNING: This is not secure against obfuscation and other evasion methods. If
+    // stronger security blocks are required, then these should be enforced in the downstream
+    // API (e.g., by having users call the MCP server with API keys with limited permissions).
+    if (blockedMethods) {
+      const blockedMatches = blockedMethods.filter((method) => code.includes(method.fullyQualifiedName));
+      if (blockedMatches.length > 0) {
+        return asErrorResult(
+          `The following methods have been blocked by the MCP server and cannot be used in code execution: ${blockedMatches
+            .map((m) => m.fullyQualifiedName)
+            .join(', ')}`,
+        );
+      }
+    }
 
-    // this is not required, but passing a Stainless API key for the matching project_name
-    // will allow you to run code-mode queries against non-published versions of your SDK.
-    const stainlessAPIKey = readEnv('STAINLESS_API_KEY');
     const codeModeEndpoint =
       readEnv('CODE_MODE_ENDPOINT_URL') ?? 'https://api.stainless.com/api/ai/code-tool';
 
+    // Setting a Stainless API key authenticates requests to the code tool endpoint.
     const res = await fetch(codeModeEndpoint, {
       method: 'POST',
       headers: {
-        ...(stainlessAPIKey && { Authorization: stainlessAPIKey }),
+        ...(reqContext.stainlessApiKey && { Authorization: reqContext.stainlessApiKey }),
         'Content-Type': 'application/json',
         client_envs: JSON.stringify({
           ROARK_API_BEARER_TOKEN: requireValue(

package/src/docs-search-tool.ts

@@ -1,7 +1,6 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
-import { Metadata, asTextContentResult } from './types';
-
+import { Metadata, McpRequestContext, asTextContentResult } from './types';
 import { Tool } from '@modelcontextprotocol/sdk/types.js';
 
 export const metadata: Metadata = {
@@ -42,10 +41,20 @@ export const tool: Tool = {
 const docsSearchURL =
   process.env['DOCS_SEARCH_URL'] || 'https://api.stainless.com/api/projects/roark-analytics/docs/search';
 
-export const handler = async (_: unknown, args: Record<string, unknown> | undefined) => {
+export const handler = async ({
+  reqContext,
+  args,
+}: {
+  reqContext: McpRequestContext;
+  args: Record<string, unknown> | undefined;
+}) => {
   const body = args as any;
   const query = new URLSearchParams(body).toString();
-  const result = await fetch(`${docsSearchURL}?${query}`);
+  const result = await fetch(`${docsSearchURL}?${query}`, {
+    headers: {
+      ...(reqContext.stainlessApiKey && { Authorization: reqContext.stainlessApiKey }),
+    },
+  });
 
   if (!result.ok) {
     throw new Error(

package/src/http.ts

@@ -2,32 +2,39 @@
 
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { ClientOptions } from '@roarkanalytics/sdk';
 import express from 'express';
 import morgan from 'morgan';
 import morganBody from 'morgan-body';
+import { getStainlessApiKey, parseClientAuthHeaders } from './auth';
 import { McpOptions } from './options';
-import { ClientOptions, initMcpServer, newMcpServer } from './server';
-import { parseAuthHeaders } from './headers';
+import { initMcpServer, newMcpServer } from './server';
 
 const newServer = async ({
   clientOptions,
+  mcpOptions,
   req,
   res,
 }: {
   clientOptions: ClientOptions;
+  mcpOptions: McpOptions;
   req: express.Request;
   res: express.Response;
 }): Promise<McpServer | null> => {
-  const server = await newMcpServer();
+  const stainlessApiKey = getStainlessApiKey(req, mcpOptions);
+  const server = await newMcpServer(stainlessApiKey);
 
   try {
-    const authOptions = parseAuthHeaders(req, false);
+    const authOptions = parseClientAuthHeaders(req, false);
+
     await initMcpServer({
       server: server,
+      mcpOptions: mcpOptions,
       clientOptions: {
         ...clientOptions,
         ...authOptions,
       },
+      stainlessApiKey: stainlessApiKey,
     });
   } catch (error) {
     res.status(401).json({
@@ -108,13 +115,17 @@ export const streamableHTTPApp = ({
   return app;
 };
 
-export const launchStreamableHTTPServer = async (params: {
+export const launchStreamableHTTPServer = async ({
+  mcpOptions,
+  debug,
+  port,
+}: {
   mcpOptions: McpOptions;
   debug: boolean;
   port: number | string | undefined;
 }) => {
-  const app = streamableHTTPApp({ mcpOptions: params.mcpOptions, debug: params.debug });
-  const server = app.listen(params.port);
+  const app = streamableHTTPApp({ mcpOptions, debug });
+  const server = app.listen(port);
   const address = server.address();
 
   if (typeof address === 'string') {
@@ -122,6 +133,6 @@ export const launchStreamableHTTPServer = async (params: {
   } 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 ${params.port}`);
+    console.error(`MCP Server running on streamable HTTP on port ${port}`);
   }
 };

package/src/index.ts

@@ -18,7 +18,7 @@ async function main() {
 
   switch (options.transport) {
     case 'stdio':
-      await launchStdioServer();
+      await launchStdioServer(options);
       break;
     case 'http':
       await launchStreamableHTTPServer({

package/src/methods.ts

@@ -0,0 +1,404 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { McpOptions } from './options';
+
+export type SdkMethod = {
+  clientCallName: string;
+  fullyQualifiedName: string;
+  httpMethod?: 'get' | 'post' | 'put' | 'patch' | 'delete' | 'query';
+  httpPath?: string;
+};
+
+export const sdkMethods: SdkMethod[] = [
+  {
+    clientCallName: 'client.health.get',
+    fullyQualifiedName: 'health.get',
+    httpMethod: 'get',
+    httpPath: '/health',
+  },
+  {
+    clientCallName: 'client.evaluation.createEvaluator',
+    fullyQualifiedName: 'evaluation.createEvaluator',
+    httpMethod: 'post',
+    httpPath: '/v1/evaluation/evaluators',
+  },
+  {
+    clientCallName: 'client.evaluation.createJob',
+    fullyQualifiedName: 'evaluation.createJob',
+    httpMethod: 'post',
+    httpPath: '/v1/evaluation/job',
+  },
+  {
+    clientCallName: 'client.evaluation.getEvaluatorByID',
+    fullyQualifiedName: 'evaluation.getEvaluatorByID',
+    httpMethod: 'get',
+    httpPath: '/v1/evaluation/evaluators/{evaluatorId}',
+  },
+  {
+    clientCallName: 'client.evaluation.getJob',
+    fullyQualifiedName: 'evaluation.getJob',
+    httpMethod: 'get',
+    httpPath: '/v1/evaluation/job/{jobId}',
+  },
+  {
+    clientCallName: 'client.evaluation.listEvaluators',
+    fullyQualifiedName: 'evaluation.listEvaluators',
+    httpMethod: 'get',
+    httpPath: '/v1/evaluation/evaluators',
+  },
+  {
+    clientCallName: 'client.evaluation.listJobRuns',
+    fullyQualifiedName: 'evaluation.listJobRuns',
+    httpMethod: 'get',
+    httpPath: '/v1/evaluation/job/{jobId}/runs',
+  },
+  {
+    clientCallName: 'client.evaluation.updateEvaluator',
+    fullyQualifiedName: 'evaluation.updateEvaluator',
+    httpMethod: 'put',
+    httpPath: '/v1/evaluation/evaluators/{evaluatorId}',
+  },
+  {
+    clientCallName: 'client.call.create',
+    fullyQualifiedName: 'call.create',
+    httpMethod: 'post',
+    httpPath: '/v1/call',
+  },
+  {
+    clientCallName: 'client.call.list',
+    fullyQualifiedName: 'call.list',
+    httpMethod: 'get',
+    httpPath: '/v1/call',
+  },
+  {
+    clientCallName: 'client.call.getByID',
+    fullyQualifiedName: 'call.getByID',
+    httpMethod: 'get',
+    httpPath: '/v1/call/{callId}',
+  },
+  {
+    clientCallName: 'client.call.getTranscript',
+    fullyQualifiedName: 'call.getTranscript',
+    httpMethod: 'get',
+    httpPath: '/v1/call/{callId}/transcript',
+  },
+  {
+    clientCallName: 'client.call.listEvaluationRuns',
+    fullyQualifiedName: 'call.listEvaluationRuns',
+    httpMethod: 'get',
+    httpPath: '/v1/call/{callId}/evaluation-run',
+  },
+  {
+    clientCallName: 'client.call.listMetrics',
+    fullyQualifiedName: 'call.listMetrics',
+    httpMethod: 'get',
+    httpPath: '/v1/call/{callId}/metrics',
+  },
+  {
+    clientCallName: 'client.call.listSentimentRuns',
+    fullyQualifiedName: 'call.listSentimentRuns',
+    httpMethod: 'get',
+    httpPath: '/v1/call/{callId}/sentiment-run',
+  },
+  {
+    clientCallName: 'client.metric.listDefinitions',
+    fullyQualifiedName: 'metric.listDefinitions',
+    httpMethod: 'get',
+    httpPath: '/v1/metric/definitions',
+  },
+  {
+    clientCallName: 'client.integrations.createRetellCall',
+    fullyQualifiedName: 'integrations.createRetellCall',
+    httpMethod: 'post',
+    httpPath: '/v1/retell/call',
+  },
+  {
+    clientCallName: 'client.integrations.createVapiCall',
+    fullyQualifiedName: 'integrations.createVapiCall',
+    httpMethod: 'post',
+    httpPath: '/v1/vapi/call',
+  },
+  {
+    clientCallName: 'client.simulationJob.getByID',
+    fullyQualifiedName: 'simulationJob.getByID',
+    httpMethod: 'get',
+    httpPath: '/v1/simulation/job/{jobId}',
+  },
+  {
+    clientCallName: 'client.simulationJob.lookup',
+    fullyQualifiedName: 'simulationJob.lookup',
+    httpMethod: 'get',
+    httpPath: '/v1/simulation/job/lookup',
+  },
+  {
+    clientCallName: 'client.simulationRunPlan.create',
+    fullyQualifiedName: 'simulationRunPlan.create',
+    httpMethod: 'post',
+    httpPath: '/v1/simulation/plan',
+  },
+  {
+    clientCallName: 'client.simulationRunPlan.update',
+    fullyQualifiedName: 'simulationRunPlan.update',
+    httpMethod: 'put',
+    httpPath: '/v1/simulation/plan/{planId}',
+  },
+  {
+    clientCallName: 'client.simulationRunPlan.list',
+    fullyQualifiedName: 'simulationRunPlan.list',
+    httpMethod: 'get',
+    httpPath: '/v1/simulation/plan',
+  },
+  {
+    clientCallName: 'client.simulationRunPlan.delete',
+    fullyQualifiedName: 'simulationRunPlan.delete',
+    httpMethod: 'delete',
+    httpPath: '/v1/simulation/plan/{planId}',
+  },
+  {
+    clientCallName: 'client.simulationRunPlan.getByID',
+    fullyQualifiedName: 'simulationRunPlan.getByID',
+    httpMethod: 'get',
+    httpPath: '/v1/simulation/plan/{planId}',
+  },
+  {
+    clientCallName: 'client.simulationRunPlanJob.list',
+    fullyQualifiedName: 'simulationRunPlanJob.list',
+    httpMethod: 'get',
+    httpPath: '/v1/simulation/plan/jobs',
+  },
+  {
+    clientCallName: 'client.simulationRunPlanJob.getByID',
+    fullyQualifiedName: 'simulationRunPlanJob.getByID',
+    httpMethod: 'get',
+    httpPath: '/v1/simulation/plan/job/{jobId}',
+  },
+  {
+    clientCallName: 'client.simulationRunPlanJob.start',
+    fullyQualifiedName: 'simulationRunPlanJob.start',
+    httpMethod: 'post',
+    httpPath: '/v1/simulation/plan/{planId}/job',
+  },
+  {
+    clientCallName: 'client.simulationScenario.create',
+    fullyQualifiedName: 'simulationScenario.create',
+    httpMethod: 'post',
+    httpPath: '/v1/simulation/scenario',
+  },
+  {
+    clientCallName: 'client.simulationScenario.update',
+    fullyQualifiedName: 'simulationScenario.update',
+    httpMethod: 'put',
+    httpPath: '/v1/simulation/scenario/{scenarioId}',
+  },
+  {
+    clientCallName: 'client.simulationScenario.list',
+    fullyQualifiedName: 'simulationScenario.list',
+    httpMethod: 'get',
+    httpPath: '/v1/simulation/scenario',
+  },
+  {
+    clientCallName: 'client.simulationScenario.delete',
+    fullyQualifiedName: 'simulationScenario.delete',
+    httpMethod: 'delete',
+    httpPath: '/v1/simulation/scenario/{scenarioId}',
+  },
+  {
+    clientCallName: 'client.simulationScenario.getByID',
+    fullyQualifiedName: 'simulationScenario.getByID',
+    httpMethod: 'get',
+    httpPath: '/v1/simulation/scenario/{scenarioId}',
+  },
+  {
+    clientCallName: 'client.simulationPersona.create',
+    fullyQualifiedName: 'simulationPersona.create',
+    httpMethod: 'post',
+    httpPath: '/v1/persona',
+  },
+  {
+    clientCallName: 'client.simulationPersona.update',
+    fullyQualifiedName: 'simulationPersona.update',
+    httpMethod: 'put',
+    httpPath: '/v1/persona/{personaId}',
+  },
+  {
+    clientCallName: 'client.simulationPersona.list',
+    fullyQualifiedName: 'simulationPersona.list',
+    httpMethod: 'get',
+    httpPath: '/v1/persona',
+  },
+  {
+    clientCallName: 'client.simulationPersona.getByID',
+    fullyQualifiedName: 'simulationPersona.getByID',
+    httpMethod: 'get',
+    httpPath: '/v1/persona/{personaId}',
+  },
+  {
+    clientCallName: 'client.agent.create',
+    fullyQualifiedName: 'agent.create',
+    httpMethod: 'post',
+    httpPath: '/v1/agent',
+  },
+  {
+    clientCallName: 'client.agent.update',
+    fullyQualifiedName: 'agent.update',
+    httpMethod: 'put',
+    httpPath: '/v1/agent/{agentId}',
+  },
+  {
+    clientCallName: 'client.agent.list',
+    fullyQualifiedName: 'agent.list',
+    httpMethod: 'get',
+    httpPath: '/v1/agent',
+  },
+  {
+    clientCallName: 'client.agent.getByID',
+    fullyQualifiedName: 'agent.getByID',
+    httpMethod: 'get',
+    httpPath: '/v1/agent/{agentId}',
+  },
+  {
+    clientCallName: 'client.agentEndpoint.create',
+    fullyQualifiedName: 'agentEndpoint.create',
+    httpMethod: 'post',
+    httpPath: '/v1/agent/endpoint',
+  },
+  {
+    clientCallName: 'client.agentEndpoint.update',
+    fullyQualifiedName: 'agentEndpoint.update',
+    httpMethod: 'put',
+    httpPath: '/v1/agent/endpoint/{endpointId}',
+  },
+  {
+    clientCallName: 'client.agentEndpoint.list',
+    fullyQualifiedName: 'agentEndpoint.list',
+    httpMethod: 'get',
+    httpPath: '/v1/agent/endpoint',
+  },
+  {
+    clientCallName: 'client.agentEndpoint.getByID',
+    fullyQualifiedName: 'agentEndpoint.getByID',
+    httpMethod: 'get',
+    httpPath: '/v1/agent/endpoint/{endpointId}',
+  },
+  {
+    clientCallName: 'client.httpRequestDefinition.create',
+    fullyQualifiedName: 'httpRequestDefinition.create',
+    httpMethod: 'post',
+    httpPath: '/v1/http-request-definition',
+  },
+  {
+    clientCallName: 'client.httpRequestDefinition.update',
+    fullyQualifiedName: 'httpRequestDefinition.update',
+    httpMethod: 'put',
+    httpPath: '/v1/http-request-definition/{definitionId}',
+  },
+  {
+    clientCallName: 'client.httpRequestDefinition.list',
+    fullyQualifiedName: 'httpRequestDefinition.list',
+    httpMethod: 'get',
+    httpPath: '/v1/http-request-definition',
+  },
+  {
+    clientCallName: 'client.httpRequestDefinition.getByID',
+    fullyQualifiedName: 'httpRequestDefinition.getByID',
+    httpMethod: 'get',
+    httpPath: '/v1/http-request-definition/{definitionId}',
+  },
+  {
+    clientCallName: 'client.webhook.create',
+    fullyQualifiedName: 'webhook.create',
+    httpMethod: 'post',
+    httpPath: '/v1/webhook',
+  },
+  {
+    clientCallName: 'client.webhook.list',
+    fullyQualifiedName: 'webhook.list',
+    httpMethod: 'get',
+    httpPath: '/v1/webhook',
+  },
+  {
+    clientCallName: 'client.webhook.delete',
+    fullyQualifiedName: 'webhook.delete',
+    httpMethod: 'delete',
+    httpPath: '/v1/webhook/{webhookId}',
+  },
+  {
+    clientCallName: 'client.webhook.getByID',
+    fullyQualifiedName: 'webhook.getByID',
+    httpMethod: 'get',
+    httpPath: '/v1/webhook/{webhookId}',
+  },
+];
+
+function allowedMethodsForCodeTool(options: McpOptions | undefined): SdkMethod[] | undefined {
+  if (!options) {
+    return undefined;
+  }
+
+  let allowedMethods: SdkMethod[];
+
+  if (options.codeAllowHttpGets || options.codeAllowedMethods) {
+    // Start with nothing allowed and then add into it from options
+    let allowedMethodsSet = new Set<SdkMethod>();
+
+    if (options.codeAllowHttpGets) {
+      // Add all methods that map to an HTTP GET
+      sdkMethods
+        .filter((method) => method.httpMethod === 'get')
+        .forEach((method) => allowedMethodsSet.add(method));
+    }
+
+    if (options.codeAllowedMethods) {
+      // Add all methods that match any of the allowed regexps
+      const allowedRegexps = options.codeAllowedMethods.map((pattern) => {
+        try {
+          return new RegExp(pattern);
+        } catch (e) {
+          throw new Error(
+            `Invalid regex pattern for allowed method: "${pattern}": ${e instanceof Error ? e.message : e}`,
+          );
+        }
+      });
+
+      sdkMethods
+        .filter((method) => allowedRegexps.some((regexp) => regexp.test(method.fullyQualifiedName)))
+        .forEach((method) => allowedMethodsSet.add(method));
+    }
+
+    allowedMethods = Array.from(allowedMethodsSet);
+  } else {
+    // Start with everything allowed
+    allowedMethods = [...sdkMethods];
+  }
+
+  if (options.codeBlockedMethods) {
+    // Filter down based on blocked regexps
+    const blockedRegexps = options.codeBlockedMethods.map((pattern) => {
+      try {
+        return new RegExp(pattern);
+      } catch (e) {
+        throw new Error(
+          `Invalid regex pattern for blocked method: "${pattern}": ${e instanceof Error ? e.message : e}`,
+        );
+      }
+    });
+
+    allowedMethods = allowedMethods.filter(
+      (method) => !blockedRegexps.some((regexp) => regexp.test(method.fullyQualifiedName)),
+    );
+  }
+
+  return allowedMethods;
+}
+
+export function blockedMethodsForCodeTool(options: McpOptions | undefined): SdkMethod[] | undefined {
+  const allowedMethods = allowedMethodsForCodeTool(options);
+  if (!allowedMethods) {
+    return undefined;
+  }
+
+  const allowedSet = new Set(allowedMethods.map((method) => method.fullyQualifiedName));
+
+  // Return any methods that are not explicitly allowed
+  return sdkMethods.filter((method) => !allowedSet.has(method.fullyQualifiedName));
+}

package/src/options.ts

@@ -1,7 +1,10 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
 import qs from 'qs';
 import yargs from 'yargs';
 import { hideBin } from 'yargs/helpers';
 import z from 'zod';
+import { readEnv } from './util';
 
 export type CLIOptions = McpOptions & {
   debug: boolean;
@@ -12,10 +15,31 @@ export type CLIOptions = McpOptions & {
 
 export type McpOptions = {
   includeDocsTools?: boolean | undefined;
+  stainlessApiKey?: string | undefined;
+  codeAllowHttpGets?: boolean | undefined;
+  codeAllowedMethods?: string[] | undefined;
+  codeBlockedMethods?: string[] | undefined;
 };
 
 export function parseCLIOptions(): CLIOptions {
   const opts = yargs(hideBin(process.argv))
+    .option('code-allow-http-gets', {
+      type: 'boolean',
+      description:
+        'Allow all code tool methods that map to HTTP GET operations. If all code-allow-* flags are unset, then everything is allowed.',
+    })
+    .option('code-allowed-methods', {
+      type: 'string',
+      array: true,
+      description:
+        'Methods to explicitly allow for code tool. Evaluated as regular expressions against method fully qualified names. If all code-allow-* flags are unset, then everything is allowed.',
+    })
+    .option('code-blocked-methods', {
+      type: 'string',
+      array: true,
+      description:
+        'Methods to explicitly block for code tool. Evaluated as regular expressions against method fully qualified names. If all code-allow-* flags are unset, then everything is allowed.',
+    })
     .option('debug', { type: 'boolean', description: 'Enable debug logging' })
     .option('no-tools', {
       type: 'string',
@@ -29,6 +53,12 @@ export function parseCLIOptions(): CLIOptions {
       description: 'Port to serve on if using http transport',
     })
     .option('socket', { type: 'string', description: 'Unix socket to serve on if using http transport' })
+    .option('stainless-api-key', {
+      type: 'string',
+      default: readEnv('STAINLESS_API_KEY'),
+      description:
+        'API key for Stainless. Used to authenticate requests to Stainless-hosted tools endpoints.',
+    })
     .option('tools', {
       type: 'string',
       array: true,
@@ -59,6 +89,10 @@ export function parseCLIOptions(): CLIOptions {
   return {
     ...(includeDocsTools !== undefined && { includeDocsTools }),
     debug: !!argv.debug,
+    stainlessApiKey: argv.stainlessApiKey,
+    codeAllowHttpGets: argv.codeAllowHttpGets,
+    codeAllowedMethods: argv.codeAllowedMethods,
+    codeBlockedMethods: argv.codeBlockedMethods,
     transport,
     port: argv.port,
     socket: argv.socket,