nimble-js-mcp 0.5.1

package/src/methods.ts

@@ -0,0 +1,176 @@
+// 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.extract',
+    fullyQualifiedName: 'extract',
+    httpMethod: 'post',
+    httpPath: '/v1/extract',
+  },
+  {
+    clientCallName: 'client.extractAsync',
+    fullyQualifiedName: 'extractAsync',
+    httpMethod: 'post',
+    httpPath: '/v1/extract/async',
+  },
+  {
+    clientCallName: 'client.map',
+    fullyQualifiedName: 'map',
+    httpMethod: 'post',
+    httpPath: '/v1/map',
+  },
+  {
+    clientCallName: 'client.search',
+    fullyQualifiedName: 'search',
+    httpMethod: 'post',
+    httpPath: '/v1/search',
+  },
+  {
+    clientCallName: 'client.agent.list',
+    fullyQualifiedName: 'agent.list',
+    httpMethod: 'get',
+    httpPath: '/v1/agents',
+  },
+  {
+    clientCallName: 'client.agent.get',
+    fullyQualifiedName: 'agent.get',
+    httpMethod: 'get',
+    httpPath: '/v1/agents/{template_name}',
+  },
+  {
+    clientCallName: 'client.agent.run',
+    fullyQualifiedName: 'agent.run',
+    httpMethod: 'post',
+    httpPath: '/v1/agents/run',
+  },
+  {
+    clientCallName: 'client.agent.runAsync',
+    fullyQualifiedName: 'agent.runAsync',
+    httpMethod: 'post',
+    httpPath: '/v1/agents/async',
+  },
+  {
+    clientCallName: 'client.crawl.list',
+    fullyQualifiedName: 'crawl.list',
+    httpMethod: 'get',
+    httpPath: '/v1/crawl',
+  },
+  {
+    clientCallName: 'client.crawl.run',
+    fullyQualifiedName: 'crawl.run',
+    httpMethod: 'post',
+    httpPath: '/v1/crawl',
+  },
+  {
+    clientCallName: 'client.crawl.status',
+    fullyQualifiedName: 'crawl.status',
+    httpMethod: 'get',
+    httpPath: '/v1/crawl/{id}',
+  },
+  {
+    clientCallName: 'client.crawl.terminate',
+    fullyQualifiedName: 'crawl.terminate',
+    httpMethod: 'delete',
+    httpPath: '/v1/crawl/{id}',
+  },
+  {
+    clientCallName: 'client.tasks.list',
+    fullyQualifiedName: 'tasks.list',
+    httpMethod: 'get',
+    httpPath: '/v1/tasks',
+  },
+  {
+    clientCallName: 'client.tasks.get',
+    fullyQualifiedName: 'tasks.get',
+    httpMethod: 'get',
+    httpPath: '/v1/tasks/{task_id}',
+  },
+  {
+    clientCallName: 'client.tasks.results',
+    fullyQualifiedName: 'tasks.results',
+    httpMethod: 'get',
+    httpPath: '/v1/tasks/{task_id}/results',
+  },
+];
+
+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

@@ -0,0 +1,129 @@
+// 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;
+  transport: 'stdio' | 'http';
+  port: number | undefined;
+  socket: string | undefined;
+};
+
+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',
+      array: true,
+      choices: ['code', 'docs'],
+      description: 'Tools to explicitly disable',
+    })
+    .option('port', {
+      type: 'number',
+      default: 3000,
+      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,
+      choices: ['code', 'docs'],
+      description: 'Tools to explicitly enable',
+    })
+    .option('transport', {
+      type: 'string',
+      choices: ['stdio', 'http'],
+      default: 'stdio',
+      description: 'What transport to use; stdio for local servers or http for remote servers',
+    })
+    .env('MCP_SERVER')
+    .version(true)
+    .help();
+
+  const argv = opts.parseSync();
+
+  const shouldIncludeToolType = (toolType: 'code' | 'docs') =>
+    argv.noTools?.includes(toolType) ? false
+    : argv.tools?.includes(toolType) ? true
+    : undefined;
+
+  const includeDocsTools = shouldIncludeToolType('docs');
+
+  const transport = argv.transport as 'stdio' | 'http';
+
+  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,
+  };
+}
+
+const coerceArray = <T extends z.ZodTypeAny>(zodType: T) =>
+  z.preprocess(
+    (val) =>
+      Array.isArray(val) ? val
+      : val ? [val]
+      : val,
+    z.array(zodType).optional(),
+  );
+
+const QueryOptions = z.object({
+  tools: coerceArray(z.enum(['code', 'docs'])).describe('Specify which MCP tools to use'),
+  no_tools: coerceArray(z.enum(['code', 'docs'])).describe('Specify which MCP tools to not use.'),
+  tool: coerceArray(z.string()).describe('Include tools matching the specified names'),
+});
+
+export function parseQueryOptions(defaultOptions: McpOptions, query: unknown): McpOptions {
+  const queryObject = typeof query === 'string' ? qs.parse(query) : query;
+  const queryOptions = QueryOptions.parse(queryObject);
+
+  let docsTools: boolean | undefined =
+    queryOptions.no_tools && queryOptions.no_tools?.includes('docs') ? false
+    : queryOptions.tools?.includes('docs') ? true
+    : defaultOptions.includeDocsTools;
+
+  return {
+    ...(docsTools !== undefined && { includeDocsTools: docsTools }),
+  };
+}

package/src/server.ts

@@ -0,0 +1,183 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+  SetLevelRequestSchema,
+} from '@modelcontextprotocol/sdk/types.js';
+import { ClientOptions } from '@nimble-way/nimble-js';
+import Nimble from '@nimble-way/nimble-js';
+import { codeTool } from './code-tool';
+import docsSearchTool from './docs-search-tool';
+import { getInstructions } from './instructions';
+import { McpOptions } from './options';
+import { blockedMethodsForCodeTool } from './methods';
+import { HandlerFunction, McpRequestContext, ToolCallResult, McpTool } from './types';
+
+export const newMcpServer = async (stainlessApiKey: string | undefined) =>
+  new McpServer(
+    {
+      name: 'nimble_way_nimble_js_api',
+      version: '0.5.1',
+    },
+    {
+      instructions: await getInstructions(stainlessApiKey),
+      capabilities: { tools: {}, logging: {} },
+    },
+  );
+
+/**
+ * Initializes the provided MCP Server with the given tools and handlers.
+ * If not provided, the default client, tools and handlers will be used.
+ */
+export async function initMcpServer(params: {
+  server: Server | McpServer;
+  clientOptions?: ClientOptions;
+  mcpOptions?: McpOptions;
+  stainlessApiKey?: string | undefined;
+}) {
+  const server = params.server instanceof McpServer ? params.server.server : params.server;
+
+  const logAtLevel =
+    (level: 'debug' | 'info' | 'warning' | 'error') =>
+    (message: string, ...rest: unknown[]) => {
+      void server.sendLoggingMessage({
+        level,
+        data: { message, rest },
+      });
+    };
+  const logger = {
+    debug: logAtLevel('debug'),
+    info: logAtLevel('info'),
+    warn: logAtLevel('warning'),
+    error: logAtLevel('error'),
+  };
+
+  let _client: Nimble | undefined;
+  let _clientError: Error | undefined;
+  let _logLevel: 'debug' | 'info' | 'warn' | 'error' | 'off' | undefined;
+
+  const getClient = (): Nimble => {
+    if (_clientError) throw _clientError;
+    if (!_client) {
+      try {
+        _client = new Nimble({
+          logger,
+          ...params.clientOptions,
+          defaultHeaders: {
+            ...params.clientOptions?.defaultHeaders,
+            'X-Stainless-MCP': 'true',
+          },
+        });
+        if (_logLevel) {
+          _client = _client.withOptions({ logLevel: _logLevel });
+        }
+      } catch (e) {
+        _clientError = e instanceof Error ? e : new Error(String(e));
+        throw _clientError;
+      }
+    }
+    return _client;
+  };
+
+  const providedTools = selectTools(params.mcpOptions);
+  const toolMap = Object.fromEntries(providedTools.map((mcpTool) => [mcpTool.tool.name, mcpTool]));
+
+  server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return {
+      tools: providedTools.map((mcpTool) => mcpTool.tool),
+    };
+  });
+
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    const mcpTool = toolMap[name];
+    if (!mcpTool) {
+      throw new Error(`Unknown tool: ${name}`);
+    }
+
+    let client: Nimble;
+    try {
+      client = getClient();
+    } catch (error) {
+      return {
+        content: [
+          {
+            type: 'text' as const,
+            text: `Failed to initialize client: ${error instanceof Error ? error.message : String(error)}`,
+          },
+        ],
+        isError: true,
+      };
+    }
+
+    return executeHandler({
+      handler: mcpTool.handler,
+      reqContext: {
+        client,
+        stainlessApiKey: params.stainlessApiKey ?? params.mcpOptions?.stainlessApiKey,
+      },
+      args,
+    });
+  });
+
+  server.setRequestHandler(SetLevelRequestSchema, async (request) => {
+    const { level } = request.params;
+    let logLevel: 'debug' | 'info' | 'warn' | 'error' | 'off';
+    switch (level) {
+      case 'debug':
+        logLevel = 'debug';
+        break;
+      case 'info':
+        logLevel = 'info';
+        break;
+      case 'notice':
+      case 'warning':
+        logLevel = 'warn';
+        break;
+      case 'error':
+        logLevel = 'error';
+        break;
+      default:
+        logLevel = 'off';
+        break;
+    }
+    _logLevel = logLevel;
+    if (_client) {
+      _client = _client.withOptions({ logLevel });
+    }
+    return {};
+  });
+}
+
+/**
+ * Selects the tools to include in the MCP Server based on the provided options.
+ */
+export function selectTools(options?: McpOptions): McpTool[] {
+  const includedTools = [
+    codeTool({
+      blockedMethods: blockedMethodsForCodeTool(options),
+    }),
+  ];
+  if (options?.includeDocsTools ?? true) {
+    includedTools.push(docsSearchTool);
+  }
+  return includedTools;
+}
+
+/**
+ * Runs the provided handler with the given client and arguments.
+ */
+export async function executeHandler({
+  handler,
+  reqContext,
+  args,
+}: {
+  handler: HandlerFunction;
+  reqContext: McpRequestContext;
+  args: Record<string, unknown> | undefined;
+}): Promise<ToolCallResult> {
+  return await handler({ reqContext, args: args || {} });
+}

package/src/stdio.ts

@@ -0,0 +1,13 @@
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { McpOptions } from './options';
+import { initMcpServer, newMcpServer } from './server';
+
+export const launchStdioServer = async (mcpOptions: McpOptions) => {
+  const server = await newMcpServer(mcpOptions.stainlessApiKey);
+
+  await initMcpServer({ server, mcpOptions, stainlessApiKey: mcpOptions.stainlessApiKey });
+
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error('MCP Server running on stdio');
+};

package/src/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  // this config is included in the published src directory to prevent TS errors
+  // from appearing when users go to source, and VSCode opens the source .ts file
+  // via declaration maps
+  "include": ["index.ts"],
+  "compilerOptions": {
+    "target": "es2015",
+    "lib": ["DOM"],
+    "moduleResolution": "node"
+  }
+}

package/src/types.ts

@@ -0,0 +1,123 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import Nimble from '@nimble-way/nimble-js';
+import { Tool } from '@modelcontextprotocol/sdk/types.js';
+
+type TextContentBlock = {
+  type: 'text';
+  text: string;
+};
+
+type ImageContentBlock = {
+  type: 'image';
+  data: string;
+  mimeType: string;
+};
+
+type AudioContentBlock = {
+  type: 'audio';
+  data: string;
+  mimeType: string;
+};
+
+type ResourceContentBlock = {
+  type: 'resource';
+  resource:
+    | {
+        uri: string;
+        mimeType: string;
+        text: string;
+      }
+    | {
+        uri: string;
+        mimeType: string;
+        blob: string;
+      };
+};
+
+export type ContentBlock = TextContentBlock | ImageContentBlock | AudioContentBlock | ResourceContentBlock;
+
+export type ToolCallResult = {
+  content: ContentBlock[];
+  isError?: boolean;
+};
+
+export type McpRequestContext = {
+  client: Nimble;
+  stainlessApiKey?: string | undefined;
+};
+
+export type HandlerFunction = ({
+  reqContext,
+  args,
+}: {
+  reqContext: McpRequestContext;
+  args: Record<string, unknown> | undefined;
+}) => Promise<ToolCallResult>;
+
+export function asTextContentResult(result: unknown): ToolCallResult {
+  return {
+    content: [
+      {
+        type: 'text',
+        text: JSON.stringify(result, null, 2),
+      },
+    ],
+  };
+}
+
+export async function asBinaryContentResult(response: Response): Promise<ToolCallResult> {
+  const blob = await response.blob();
+  const mimeType = blob.type;
+  const data = Buffer.from(await blob.arrayBuffer()).toString('base64');
+  if (mimeType.startsWith('image/')) {
+    return {
+      content: [{ type: 'image', mimeType, data }],
+    };
+  } else if (mimeType.startsWith('audio/')) {
+    return {
+      content: [{ type: 'audio', mimeType, data }],
+    };
+  } else {
+    return {
+      content: [
+        {
+          type: 'resource',
+          resource: {
+            // We must give a URI, even though this isn't actually an MCP resource.
+            uri: 'resource://tool-response',
+            mimeType,
+            blob: data,
+          },
+        },
+      ],
+    };
+  }
+}
+
+export function asErrorResult(message: string): ToolCallResult {
+  return {
+    content: [
+      {
+        type: 'text',
+        text: message,
+      },
+    ],
+    isError: true,
+  };
+}
+
+export type Metadata = {
+  resource: string;
+  operation: 'read' | 'write';
+  tags: string[];
+  httpMethod?: string;
+  httpPath?: string;
+  operationId?: string;
+};
+
+export type McpTool = {
+  metadata: Metadata;
+  tool: Tool;
+  handler: HandlerFunction;
+};

package/src/util.ts

@@ -0,0 +1,25 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+export const readEnv = (env: string): string | undefined => {
+  if (typeof (globalThis as any).process !== 'undefined') {
+    return (globalThis as any).process.env?.[env]?.trim();
+  } else if (typeof (globalThis as any).Deno !== 'undefined') {
+    return (globalThis as any).Deno.env?.get?.(env)?.trim();
+  }
+  return;
+};
+
+export const readEnvOrError = (env: string): string => {
+  let envValue = readEnv(env);
+  if (envValue === undefined) {
+    throw new Error(`Environment variable ${env} is not set`);
+  }
+  return envValue;
+};
+
+export const requireValue = <T>(value: T | undefined, description: string): T => {
+  if (value === undefined) {
+    throw new Error(`Missing required value: ${description}`);
+  }
+  return value;
+};

package/stdio.d.mts

@@ -0,0 +1,3 @@
+import { McpOptions } from "./options.mjs";
+export declare const launchStdioServer: (mcpOptions: McpOptions) => Promise<void>;
+//# sourceMappingURL=stdio.d.mts.map

package/stdio.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stdio.d.mts","sourceRoot":"","sources":["src/stdio.ts"],"names":[],"mappings":"OACO,EAAE,UAAU,EAAE;AAGrB,eAAO,MAAM,iBAAiB,GAAU,YAAY,UAAU,kBAQ7D,CAAC"}

package/stdio.d.ts

@@ -0,0 +1,3 @@
+import { McpOptions } from "./options.js";
+export declare const launchStdioServer: (mcpOptions: McpOptions) => Promise<void>;
+//# sourceMappingURL=stdio.d.ts.map

package/stdio.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stdio.d.ts","sourceRoot":"","sources":["src/stdio.ts"],"names":[],"mappings":"OACO,EAAE,UAAU,EAAE;AAGrB,eAAO,MAAM,iBAAiB,GAAU,YAAY,UAAU,kBAQ7D,CAAC"}

package/stdio.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.launchStdioServer = void 0;
+const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
+const server_1 = require("./server.js");
+const launchStdioServer = async (mcpOptions) => {
+    const server = await (0, server_1.newMcpServer)(mcpOptions.stainlessApiKey);
+    await (0, server_1.initMcpServer)({ server, mcpOptions, stainlessApiKey: mcpOptions.stainlessApiKey });
+    const transport = new stdio_js_1.StdioServerTransport();
+    await server.connect(transport);
+    console.error('MCP Server running on stdio');
+};
+exports.launchStdioServer = launchStdioServer;
+//# sourceMappingURL=stdio.js.map

package/stdio.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stdio.js","sourceRoot":"","sources":["src/stdio.ts"],"names":[],"mappings":";;;AAAA,wEAAiF;AAEjF,wCAAuD;AAEhD,MAAM,iBAAiB,GAAG,KAAK,EAAE,UAAsB,EAAE,EAAE;IAChE,MAAM,MAAM,GAAG,MAAM,IAAA,qBAAY,EAAC,UAAU,CAAC,eAAe,CAAC,CAAC;IAE9D,MAAM,IAAA,sBAAa,EAAC,EAAE,MAAM,EAAE,UAAU,EAAE,eAAe,EAAE,UAAU,CAAC,eAAe,EAAE,CAAC,CAAC;IAEzF,MAAM,SAAS,GAAG,IAAI,+BAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAChC,OAAO,CAAC,KAAK,CAAC,6BAA6B,CAAC,CAAC;AAC/C,CAAC,CAAC;AARW,QAAA,iBAAiB,qBAQ5B"}