@lightsparkdev/grid-mcp 0.3.0

package/src/methods.ts

@@ -0,0 +1,348 @@
+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.config.retrieve',
+    fullyQualifiedName: 'config.retrieve',
+    httpMethod: 'get',
+    httpPath: '/config',
+  },
+  {
+    clientCallName: 'client.config.update',
+    fullyQualifiedName: 'config.update',
+    httpMethod: 'patch',
+    httpPath: '/config',
+  },
+  {
+    clientCallName: 'client.customers.create',
+    fullyQualifiedName: 'customers.create',
+    httpMethod: 'post',
+    httpPath: '/customers',
+  },
+  {
+    clientCallName: 'client.customers.retrieve',
+    fullyQualifiedName: 'customers.retrieve',
+    httpMethod: 'get',
+    httpPath: '/customers/{customerId}',
+  },
+  {
+    clientCallName: 'client.customers.update',
+    fullyQualifiedName: 'customers.update',
+    httpMethod: 'patch',
+    httpPath: '/customers/{customerId}',
+  },
+  {
+    clientCallName: 'client.customers.list',
+    fullyQualifiedName: 'customers.list',
+    httpMethod: 'get',
+    httpPath: '/customers',
+  },
+  {
+    clientCallName: 'client.customers.delete',
+    fullyQualifiedName: 'customers.delete',
+    httpMethod: 'delete',
+    httpPath: '/customers/{customerId}',
+  },
+  {
+    clientCallName: 'client.customers.getKYCLink',
+    fullyQualifiedName: 'customers.getKYCLink',
+    httpMethod: 'get',
+    httpPath: '/customers/kyc-link',
+  },
+  {
+    clientCallName: 'client.customers.listInternalAccounts',
+    fullyQualifiedName: 'customers.listInternalAccounts',
+    httpMethod: 'get',
+    httpPath: '/customers/internal-accounts',
+  },
+  {
+    clientCallName: 'client.customers.externalAccounts.create',
+    fullyQualifiedName: 'customers.externalAccounts.create',
+    httpMethod: 'post',
+    httpPath: '/customers/external-accounts',
+  },
+  {
+    clientCallName: 'client.customers.externalAccounts.list',
+    fullyQualifiedName: 'customers.externalAccounts.list',
+    httpMethod: 'get',
+    httpPath: '/customers/external-accounts',
+  },
+  {
+    clientCallName: 'client.customers.bulk.getJobStatus',
+    fullyQualifiedName: 'customers.bulk.getJobStatus',
+    httpMethod: 'get',
+    httpPath: '/customers/bulk/jobs/{jobId}',
+  },
+  {
+    clientCallName: 'client.customers.bulk.uploadCsv',
+    fullyQualifiedName: 'customers.bulk.uploadCsv',
+    httpMethod: 'post',
+    httpPath: '/customers/bulk/csv',
+  },
+  {
+    clientCallName: 'client.platform.listInternalAccounts',
+    fullyQualifiedName: 'platform.listInternalAccounts',
+    httpMethod: 'get',
+    httpPath: '/platform/internal-accounts',
+  },
+  {
+    clientCallName: 'client.platform.externalAccounts.create',
+    fullyQualifiedName: 'platform.externalAccounts.create',
+    httpMethod: 'post',
+    httpPath: '/platform/external-accounts',
+  },
+  {
+    clientCallName: 'client.platform.externalAccounts.list',
+    fullyQualifiedName: 'platform.externalAccounts.list',
+    httpMethod: 'get',
+    httpPath: '/platform/external-accounts',
+  },
+  {
+    clientCallName: 'client.plaid.createLinkToken',
+    fullyQualifiedName: 'plaid.createLinkToken',
+    httpMethod: 'post',
+    httpPath: '/plaid/link-tokens',
+  },
+  {
+    clientCallName: 'client.plaid.submitPublicToken',
+    fullyQualifiedName: 'plaid.submitPublicToken',
+    httpMethod: 'post',
+    httpPath: '/plaid/callback/{plaid_link_token}',
+  },
+  {
+    clientCallName: 'client.transferIn.create',
+    fullyQualifiedName: 'transferIn.create',
+    httpMethod: 'post',
+    httpPath: '/transfer-in',
+  },
+  {
+    clientCallName: 'client.transferOut.create',
+    fullyQualifiedName: 'transferOut.create',
+    httpMethod: 'post',
+    httpPath: '/transfer-out',
+  },
+  {
+    clientCallName: 'client.receiver.lookupExternalAccount',
+    fullyQualifiedName: 'receiver.lookupExternalAccount',
+    httpMethod: 'get',
+    httpPath: '/receiver/external-account/{accountId}',
+  },
+  {
+    clientCallName: 'client.receiver.lookupUma',
+    fullyQualifiedName: 'receiver.lookupUma',
+    httpMethod: 'get',
+    httpPath: '/receiver/uma/{receiverUmaAddress}',
+  },
+  {
+    clientCallName: 'client.quotes.create',
+    fullyQualifiedName: 'quotes.create',
+    httpMethod: 'post',
+    httpPath: '/quotes',
+  },
+  {
+    clientCallName: 'client.quotes.retrieve',
+    fullyQualifiedName: 'quotes.retrieve',
+    httpMethod: 'get',
+    httpPath: '/quotes/{quoteId}',
+  },
+  {
+    clientCallName: 'client.quotes.list',
+    fullyQualifiedName: 'quotes.list',
+    httpMethod: 'get',
+    httpPath: '/quotes',
+  },
+  {
+    clientCallName: 'client.quotes.execute',
+    fullyQualifiedName: 'quotes.execute',
+    httpMethod: 'post',
+    httpPath: '/quotes/{quoteId}/execute',
+  },
+  {
+    clientCallName: 'client.transactions.retrieve',
+    fullyQualifiedName: 'transactions.retrieve',
+    httpMethod: 'get',
+    httpPath: '/transactions/{transactionId}',
+  },
+  {
+    clientCallName: 'client.transactions.list',
+    fullyQualifiedName: 'transactions.list',
+    httpMethod: 'get',
+    httpPath: '/transactions',
+  },
+  {
+    clientCallName: 'client.transactions.approve',
+    fullyQualifiedName: 'transactions.approve',
+    httpMethod: 'post',
+    httpPath: '/transactions/{transactionId}/approve',
+  },
+  {
+    clientCallName: 'client.transactions.reject',
+    fullyQualifiedName: 'transactions.reject',
+    httpMethod: 'post',
+    httpPath: '/transactions/{transactionId}/reject',
+  },
+  {
+    clientCallName: 'client.webhooks.sendTest',
+    fullyQualifiedName: 'webhooks.sendTest',
+    httpMethod: 'post',
+    httpPath: '/webhooks/test',
+  },
+  {
+    clientCallName: 'client.invitations.create',
+    fullyQualifiedName: 'invitations.create',
+    httpMethod: 'post',
+    httpPath: '/invitations',
+  },
+  {
+    clientCallName: 'client.invitations.retrieve',
+    fullyQualifiedName: 'invitations.retrieve',
+    httpMethod: 'get',
+    httpPath: '/invitations/{invitationCode}',
+  },
+  {
+    clientCallName: 'client.invitations.cancel',
+    fullyQualifiedName: 'invitations.cancel',
+    httpMethod: 'post',
+    httpPath: '/invitations/{invitationCode}/cancel',
+  },
+  {
+    clientCallName: 'client.invitations.claim',
+    fullyQualifiedName: 'invitations.claim',
+    httpMethod: 'post',
+    httpPath: '/invitations/{invitationCode}/claim',
+  },
+  {
+    clientCallName: 'client.sandbox.sendFunds',
+    fullyQualifiedName: 'sandbox.sendFunds',
+    httpMethod: 'post',
+    httpPath: '/sandbox/send',
+  },
+  {
+    clientCallName: 'client.sandbox.uma.receivePayment',
+    fullyQualifiedName: 'sandbox.uma.receivePayment',
+    httpMethod: 'post',
+    httpPath: '/sandbox/uma/receive',
+  },
+  {
+    clientCallName: 'client.sandbox.internalAccounts.fund',
+    fullyQualifiedName: 'sandbox.internalAccounts.fund',
+    httpMethod: 'post',
+    httpPath: '/sandbox/internal-accounts/{accountId}/fund',
+  },
+  {
+    clientCallName: 'client.umaProviders.list',
+    fullyQualifiedName: 'umaProviders.list',
+    httpMethod: 'get',
+    httpPath: '/uma-providers',
+  },
+  {
+    clientCallName: 'client.tokens.create',
+    fullyQualifiedName: 'tokens.create',
+    httpMethod: 'post',
+    httpPath: '/tokens',
+  },
+  {
+    clientCallName: 'client.tokens.retrieve',
+    fullyQualifiedName: 'tokens.retrieve',
+    httpMethod: 'get',
+    httpPath: '/tokens/{tokenId}',
+  },
+  {
+    clientCallName: 'client.tokens.list',
+    fullyQualifiedName: 'tokens.list',
+    httpMethod: 'get',
+    httpPath: '/tokens',
+  },
+  {
+    clientCallName: 'client.tokens.delete',
+    fullyQualifiedName: 'tokens.delete',
+    httpMethod: 'delete',
+    httpPath: '/tokens/{tokenId}',
+  },
+  {
+    clientCallName: 'client.exchangeRates.list',
+    fullyQualifiedName: 'exchangeRates.list',
+    httpMethod: 'get',
+    httpPath: '/exchange-rates',
+  },
+];
+
+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,118 @@
+import qs from 'qs';
+import yargs from 'yargs';
+import { hideBin } from 'yargs/helpers';
+import z from 'zod';
+
+export type CLIOptions = McpOptions & {
+  debug: boolean;
+  transport: 'stdio' | 'http';
+  port: number | undefined;
+  socket: string | undefined;
+};
+
+export type McpOptions = {
+  includeDocsTools?: boolean | 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('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,
+    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,195 @@
+// 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 '@lightsparkdev/grid';
+import LightsparkGrid from '@lightsparkdev/grid';
+import { codeTool } from './code-tool';
+import docsSearchTool from './docs-search-tool';
+import { McpOptions } from './options';
+import { blockedMethodsForCodeTool } from './methods';
+import { HandlerFunction, McpTool } from './types';
+
+export { McpOptions } from './options';
+export { ClientOptions } from '@lightsparkdev/grid';
+
+async function getInstructions() {
+  // This API key is optional; providing it allows the server to fetch instructions for unreleased versions.
+  const stainlessAPIKey = readEnv('STAINLESS_API_KEY');
+  const response = await fetch(
+    readEnv('CODE_MODE_INSTRUCTIONS_URL') ?? 'https://api.stainless.com/api/ai/instructions/grid',
+    {
+      method: 'GET',
+      headers: { ...(stainlessAPIKey && { Authorization: stainlessAPIKey }) },
+    },
+  );
+
+  let instructions: string | undefined;
+  if (!response.ok) {
+    console.warn(
+      'Warning: failed to retrieve MCP server instructions. Proceeding with default instructions...',
+    );
+
+    instructions = `
+      This is the grid MCP server. You will use Code Mode to help the user perform
+      actions. You can use search_docs tool to learn about how to take action with this server. Then,
+      you will write TypeScript code using the execute tool take action. It is CRITICAL that you be
+      thoughtful and deliberate when executing code. Always try to entirely solve the problem in code
+      block: it can be as long as you need to get the job done!
+    `;
+  }
+
+  instructions ??= ((await response.json()) as { instructions: string }).instructions;
+  instructions = `
+    The current time in Unix timestamps is ${Date.now()}.
+
+    ${instructions}
+  `;
+
+  return instructions;
+}
+
+export const newMcpServer = async () =>
+  new McpServer(
+    {
+      name: 'lightsparkdev_grid_api',
+      version: '0.3.0',
+    },
+    {
+      instructions: await getInstructions(),
+      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;
+}) {
+  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 = new LightsparkGrid({
+    logger,
+    ...params.clientOptions,
+    defaultHeaders: {
+      ...params.clientOptions?.defaultHeaders,
+      'X-Stainless-MCP': 'true',
+    },
+  });
+
+  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}`);
+    }
+
+    return executeHandler(mcpTool.handler, client, args);
+  });
+
+  server.setRequestHandler(SetLevelRequestSchema, async (request) => {
+    const { level } = request.params;
+    switch (level) {
+      case 'debug':
+        client = client.withOptions({ logLevel: 'debug' });
+        break;
+      case 'info':
+        client = client.withOptions({ logLevel: 'info' });
+        break;
+      case 'notice':
+      case 'warning':
+        client = client.withOptions({ logLevel: 'warn' });
+        break;
+      case 'error':
+        client = client.withOptions({ logLevel: 'error' });
+        break;
+      default:
+        client = client.withOptions({ logLevel: 'off' });
+        break;
+    }
+    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: HandlerFunction,
+  client: LightsparkGrid,
+  args: Record<string, unknown> | undefined,
+) {
+  return await handler(client, args || {});
+}
+
+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/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();
+
+  await initMcpServer({ server, mcpOptions });
+
+  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"
+  }
+}