@augno/sdk-mcp 0.10.0

package/src/code-tool.ts

@@ -0,0 +1,316 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { ContentBlock, McpRequestContext, McpTool, Metadata, ToolCallResult, asErrorResult } from './types';
+import { Tool } from '@modelcontextprotocol/sdk/types.js';
+import { WorkerOutput } from './code-tool-types';
+import { getLogger } from './logger';
+import { SdkMethod } from './methods';
+import { McpCodeExecutionMode } from './options';
+import { ClientOptions } from '@augno/sdk';
+
+const prompt = `Runs JavaScript code to interact with the Augno API.
+
+You are a skilled TypeScript programmer writing code to interface with the service.
+Define an async function named "run" that takes a single parameter of an initialized SDK client and it will be run.
+For example:
+
+\`\`\`
+async function run(client) {
+  const listItem = await client.catalog.items.list();
+
+  console.log(listItem.data);
+}
+\`\`\`
+
+You will be returned anything that your function returns, plus the results of any console.log statements.
+Do not add try-catch blocks for single API calls. The tool will handle errors for you.
+Do not add comments unless necessary for generating better code.
+Code will run in a container, and cannot interact with the network outside of the given SDK client.
+Variables will not persist between calls, so make sure to return or log any data you might need later.
+Remember that you are writing TypeScript code, so you need to be careful with your types.
+Always type dynamic key-value stores explicitly as Record<string, YourValueType> instead of {}.`;
+
+/**
+ * A tool that runs code against a copy of the SDK.
+ *
+ * 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.
+ *
+ * @param blockedMethods - The methods to block for code execution. Blocking is done by simple string
+ * matching, so it is not secure against obfuscation. For stronger security, block in the downstream API
+ * with limited API keys.
+ * @param codeExecutionMode - Whether to execute code in a local Deno environment or in a remote
+ * sandbox environment hosted by Stainless.
+ */
+export function codeTool({
+  blockedMethods,
+  codeExecutionMode,
+}: {
+  blockedMethods: SdkMethod[] | undefined;
+  codeExecutionMode: McpCodeExecutionMode;
+}): McpTool {
+  const metadata: Metadata = { resource: 'all', operation: 'write', tags: [] };
+  const tool: Tool = {
+    name: 'execute',
+    description: prompt,
+    inputSchema: {
+      type: 'object',
+      properties: {
+        code: {
+          type: 'string',
+          description: 'Code to execute.',
+        },
+        intent: {
+          type: 'string',
+          description: 'Task you are trying to perform. Used for improving the service.',
+        },
+      },
+      required: ['code'],
+    },
+  };
+
+  const logger = getLogger();
+
+  const handler = async ({
+    reqContext,
+    args,
+  }: {
+    reqContext: McpRequestContext;
+    args: any;
+  }): Promise<ToolCallResult> => {
+    const code = args.code as string;
+    // 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(', ')}`,
+        );
+      }
+    }
+
+    let result: ToolCallResult;
+    const startTime = Date.now();
+
+    logger.debug('Executing code in local Deno environment');
+    result = await localDenoHandler({ reqContext, args });
+
+    logger.info(
+      {
+        codeExecutionMode,
+        durationMs: Date.now() - startTime,
+        isError: result.isError,
+        contentRows: result.content?.length ?? 0,
+      },
+      'Got code tool execution result',
+    );
+    return result;
+  };
+
+  return { metadata, tool, handler };
+}
+
+const localDenoHandler = async ({
+  reqContext,
+  args,
+}: {
+  reqContext: McpRequestContext;
+  args: unknown;
+}): Promise<ToolCallResult> => {
+  const fs = await import('node:fs');
+  const path = await import('node:path');
+  const url = await import('node:url');
+  const { newDenoHTTPWorker } = await import('@valtown/deno-http-worker');
+  const { getWorkerPath } = await import('./code-tool-paths.cjs');
+  const workerPath = getWorkerPath();
+
+  const client = reqContext.client;
+  const baseURLHostname = new URL(client.baseURL).hostname;
+  const { code } = args as { code: string };
+
+  let denoPath: string;
+
+  const packageRoot = path.resolve(path.dirname(workerPath), '..');
+  const packageNodeModulesPath = path.resolve(packageRoot, 'node_modules');
+
+  // Check if deno is in PATH
+  const { execSync } = await import('node:child_process');
+  try {
+    execSync('command -v deno', { stdio: 'ignore' });
+    denoPath = 'deno';
+  } catch {
+    try {
+      // Use deno binary in node_modules if it's found
+      const denoNodeModulesPath = path.resolve(packageNodeModulesPath, 'deno', 'bin.cjs');
+      await fs.promises.access(denoNodeModulesPath, fs.constants.X_OK);
+      denoPath = denoNodeModulesPath;
+    } catch {
+      return asErrorResult(
+        'Deno is required for code execution but was not found. ' +
+          'Install it from https://deno.land or run: npm install deno',
+      );
+    }
+  }
+
+  const allowReadPaths = [
+    'code-tool-worker.mjs',
+    `${workerPath.replace(/([\/\\]node_modules)[\/\\].+$/, '$1')}/`,
+    packageRoot,
+  ];
+
+  // Follow symlinks in node_modules to allow read access to workspace-linked packages
+  try {
+    const sdkPkgName = '@augno/sdk';
+    const sdkDir = path.resolve(packageNodeModulesPath, sdkPkgName);
+    const realSdkDir = fs.realpathSync(sdkDir);
+    if (realSdkDir !== sdkDir) {
+      allowReadPaths.push(realSdkDir);
+    }
+  } catch {
+    // Ignore if symlink resolution fails
+  }
+
+  const allowRead = allowReadPaths.join(',');
+
+  const worker = await newDenoHTTPWorker(url.pathToFileURL(workerPath), {
+    denoExecutable: denoPath,
+    runFlags: [
+      `--node-modules-dir=manual`,
+      `--allow-read=${allowRead}`,
+      `--allow-net=${baseURLHostname}`,
+      // Allow environment variables because instantiating the client will try to read from them,
+      // even though they are not set.
+      '--allow-env',
+    ],
+    printOutput: true,
+    spawnOptions: {
+      cwd: path.dirname(workerPath),
+      // Merge any upstream client envs into the Deno subprocess environment,
+      // with the upstream env vars taking precedence.
+      env: { ...process.env, ...reqContext.upstreamClientEnvs },
+    },
+  });
+
+  try {
+    const resp = await new Promise<Response>((resolve, reject) => {
+      worker.addEventListener('exit', (exitCode) => {
+        reject(new Error(`Worker exited with code ${exitCode}`));
+      });
+
+      // Strip null/undefined values so that the worker SDK client can fall back to
+      // reading from environment variables (including any upstreamClientEnvs).
+      const opts = {
+        ...(client.baseURL != null ? { baseURL: client.baseURL } : undefined),
+        ...(client.bearerToken != null ? { bearerToken: client.bearerToken } : undefined),
+        ...(client.augnoAccountID != null ? { augnoAccountID: client.augnoAccountID } : undefined),
+        defaultHeaders: {
+          'X-Stainless-MCP': 'true',
+        },
+      } satisfies Partial<ClientOptions> as ClientOptions;
+
+      const req = worker.request(
+        'http://localhost',
+        {
+          headers: {
+            'content-type': 'application/json',
+          },
+          method: 'POST',
+        },
+        (resp) => {
+          const body: Uint8Array[] = [];
+          resp.on('error', (err) => {
+            reject(err);
+          });
+          resp.on('data', (chunk) => {
+            body.push(chunk);
+          });
+          resp.on('end', () => {
+            resolve(
+              new Response(Buffer.concat(body).toString(), {
+                status: resp.statusCode ?? 200,
+                headers: resp.headers as any,
+              }),
+            );
+          });
+        },
+      );
+
+      const body = JSON.stringify({
+        opts,
+        code,
+      });
+
+      req.write(body, (err) => {
+        if (err != null) {
+          reject(err);
+        }
+      });
+
+      req.end();
+    });
+
+    if (resp.status === 200) {
+      const { result, log_lines, err_lines } = (await resp.json()) as WorkerOutput;
+      const returnOutput: ContentBlock | null =
+        result == null ? null : (
+          {
+            type: 'text',
+            text: typeof result === 'string' ? result : JSON.stringify(result),
+          }
+        );
+      const logOutput: ContentBlock | null =
+        log_lines.length === 0 ?
+          null
+        : {
+            type: 'text',
+            text: log_lines.join('\n'),
+          };
+      const errOutput: ContentBlock | null =
+        err_lines.length === 0 ?
+          null
+        : {
+            type: 'text',
+            text: 'Error output:\n' + err_lines.join('\n'),
+          };
+      return {
+        content: [returnOutput, logOutput, errOutput].filter((block) => block !== null),
+      };
+    } else {
+      const { result, log_lines, err_lines } = (await resp.json()) as WorkerOutput;
+      const messageOutput: ContentBlock | null =
+        result == null ? null : (
+          {
+            type: 'text',
+            text: typeof result === 'string' ? result : JSON.stringify(result),
+          }
+        );
+      const logOutput: ContentBlock | null =
+        log_lines.length === 0 ?
+          null
+        : {
+            type: 'text',
+            text: log_lines.join('\n'),
+          };
+      const errOutput: ContentBlock | null =
+        err_lines.length === 0 ?
+          null
+        : {
+            type: 'text',
+            text: 'Error output:\n' + err_lines.join('\n'),
+          };
+      return {
+        content: [messageOutput, logOutput, errOutput].filter((block) => block !== null),
+        isError: true,
+      };
+    }
+  } finally {
+    worker.terminate();
+  }
+};

package/src/http.ts

@@ -0,0 +1,227 @@
+// 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 { ClientOptions } from '@augno/sdk';
+import express from 'express';
+import pino from 'pino';
+import pinoHttp from 'pino-http';
+import { getStainlessApiKey, parseClientAuthHeaders } from './auth';
+import { getLogger } from './logger';
+import { McpOptions } from './options';
+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 stainlessApiKey = getStainlessApiKey(req, mcpOptions);
+  const customInstructionsPath = mcpOptions.customInstructionsPath;
+  const server = await newMcpServer({ stainlessApiKey, customInstructionsPath });
+
+  const authOptions = parseClientAuthHeaders(req, false);
+
+  let upstreamClientEnvs: Record<string, string> | undefined;
+  const clientEnvsHeader = req.headers['x-stainless-mcp-client-envs'];
+  if (typeof clientEnvsHeader === 'string') {
+    try {
+      const parsed = JSON.parse(clientEnvsHeader);
+      if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+        upstreamClientEnvs = parsed;
+      }
+    } catch {
+      // Ignore malformed header
+    }
+  }
+
+  // Parse x-stainless-mcp-client-permissions header to override permission options
+  //
+  // Note: Permissions are best-effort and intended to prevent clients from doing unexpected things;
+  // they're not a hard security boundary, so we allow arbitrary, client-driven overrides.
+  //
+  // See the Stainless MCP documentation for more details.
+  let effectiveMcpOptions = mcpOptions;
+  const clientPermissionsHeader = req.headers['x-stainless-mcp-client-permissions'];
+  if (typeof clientPermissionsHeader === 'string') {
+    try {
+      const parsed = JSON.parse(clientPermissionsHeader);
+      if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+        effectiveMcpOptions = {
+          ...mcpOptions,
+          ...(typeof parsed.allow_http_gets === 'boolean' && { codeAllowHttpGets: parsed.allow_http_gets }),
+          ...(Array.isArray(parsed.allowed_methods) && { codeAllowedMethods: parsed.allowed_methods }),
+          ...(Array.isArray(parsed.blocked_methods) && { codeBlockedMethods: parsed.blocked_methods }),
+        };
+        getLogger().info(
+          { clientPermissions: parsed },
+          'Overriding code execution permissions from x-stainless-mcp-client-permissions header',
+        );
+      }
+    } catch (error) {
+      getLogger().warn({ error }, 'Failed to parse x-stainless-mcp-client-permissions header');
+    }
+  }
+
+  const mcpClientInfo =
+    typeof req.body?.params?.clientInfo?.name === 'string' ?
+      { name: req.body.params.clientInfo.name, version: String(req.body.params.clientInfo.version ?? '') }
+    : undefined;
+
+  await initMcpServer({
+    server: server,
+    mcpOptions: effectiveMcpOptions,
+    clientOptions: {
+      ...clientOptions,
+      ...authOptions,
+    },
+    stainlessApiKey: stainlessApiKey,
+    upstreamClientEnvs,
+    mcpSessionId: (req as any).mcpSessionId,
+    mcpClientInfo,
+  });
+
+  if (mcpClientInfo) {
+    getLogger().info({ mcpSessionId: (req as any).mcpSessionId, mcpClientInfo }, 'MCP client connected');
+  }
+
+  return server;
+};
+
+const post =
+  (options: { clientOptions: ClientOptions; mcpOptions: McpOptions }) =>
+  async (req: express.Request, res: express.Response) => {
+    const server = await newServer({ ...options, req, res });
+    // If we return null, we already set the authorization error.
+    if (server === null) return;
+    const transport = new StreamableHTTPServerTransport();
+    await server.connect(transport as any);
+    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',
+    },
+  });
+};
+
+const redactHeaders = (headers: Record<string, any>) => {
+  const hiddenHeaders = /auth|cookie|key|token|x-stainless-mcp-client-envs/i;
+  const filtered = { ...headers };
+  Object.keys(filtered).forEach((key) => {
+    if (hiddenHeaders.test(key)) {
+      filtered[key] = '[REDACTED]';
+    }
+  });
+  return filtered;
+};
+
+export const streamableHTTPApp = ({
+  clientOptions = {},
+  mcpOptions,
+}: {
+  clientOptions?: ClientOptions;
+  mcpOptions: McpOptions;
+}): express.Express => {
+  const app = express();
+  app.set('query parser', 'extended');
+  app.use(express.json());
+  app.use((req: express.Request, res: express.Response, next: express.NextFunction) => {
+    const existing = req.headers['mcp-session-id'];
+    const sessionId = (Array.isArray(existing) ? existing[0] : existing) || crypto.randomUUID();
+    (req as any).mcpSessionId = sessionId;
+    const origWriteHead = res.writeHead.bind(res);
+    res.writeHead = function (statusCode: number, ...rest: any[]) {
+      res.setHeader('mcp-session-id', sessionId);
+      return origWriteHead(statusCode, ...rest);
+    } as typeof res.writeHead;
+    next();
+  });
+  app.use(
+    pinoHttp({
+      logger: getLogger(),
+      customProps: (req) => ({
+        mcpSessionId: (req as any).mcpSessionId,
+      }),
+      customLogLevel: (req, res) => {
+        if (res.statusCode >= 500) {
+          return 'error';
+        } else if (res.statusCode >= 400) {
+          return 'warn';
+        }
+        return 'info';
+      },
+      customSuccessMessage: function (req, res) {
+        return `Request ${req.method} to ${req.url} completed with status ${res.statusCode}`;
+      },
+      customErrorMessage: function (req, res, err) {
+        return `Request ${req.method} to ${req.url} errored with status ${res.statusCode}`;
+      },
+      serializers: {
+        req: pino.stdSerializers.wrapRequestSerializer((req) => {
+          return {
+            ...req,
+            headers: redactHeaders(req.raw.headers),
+          };
+        }),
+        res: pino.stdSerializers.wrapResponseSerializer((res) => {
+          return {
+            ...res,
+            headers: redactHeaders(res.headers),
+          };
+        }),
+      },
+    }),
+  );
+
+  app.get('/health', async (req: express.Request, res: express.Response) => {
+    res.status(200).send('OK');
+  });
+  app.get('/', get);
+  app.post('/', post({ clientOptions, mcpOptions }));
+  app.delete('/', del);
+
+  return app;
+};
+
+export const launchStreamableHTTPServer = async ({
+  mcpOptions,
+  port,
+}: {
+  mcpOptions: McpOptions;
+  port: number | string | undefined;
+}) => {
+  const app = streamableHTTPApp({ mcpOptions });
+  const server = app.listen(port);
+  const address = server.address();
+
+  const logger = getLogger();
+
+  if (typeof address === 'string') {
+    logger.info(`MCP Server running on streamable HTTP at ${address}`);
+  } else if (address !== null) {
+    logger.info(`MCP Server running on streamable HTTP on port ${address.port}`);
+  } else {
+    logger.info(`MCP Server running on streamable HTTP on port ${port}`);
+  }
+};

package/src/index.ts

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+
+import { selectTools } from './server';
+import { McpOptions, parseCLIOptions } from './options';
+import { launchStdioServer } from './stdio';
+import { launchStreamableHTTPServer } from './http';
+import type { McpTool } from './types';
+import { configureLogger, getLogger } from './logger';
+
+async function main() {
+  const options = parseOptionsOrError();
+  configureLogger({
+    level: options.debug ? 'debug' : 'info',
+    pretty: options.logFormat === 'pretty',
+  });
+
+  const selectedTools = await selectToolsOrError(options);
+
+  getLogger().info(
+    { tools: selectedTools.map((e) => e.tool.name) },
+    `MCP Server starting with ${selectedTools.length} tools`,
+  );
+
+  switch (options.transport) {
+    case 'stdio':
+      await launchStdioServer(options);
+      break;
+    case 'http':
+      await launchStreamableHTTPServer({
+        mcpOptions: options,
+        port: options.socket ?? options.port,
+      });
+      break;
+  }
+}
+
+if (require.main === module) {
+  main().catch((error) => {
+    // Logger might not be initialized yet
+    console.error('Fatal error in main()', error);
+    process.exit(1);
+  });
+}
+
+function parseOptionsOrError() {
+  try {
+    return parseCLIOptions();
+  } catch (error) {
+    // Logger is initialized after options, so use console.error here
+    console.error('Error parsing options', error);
+    process.exit(1);
+  }
+}
+
+async function selectToolsOrError(options: McpOptions): Promise<McpTool[]> {
+  try {
+    const includedTools = selectTools(options);
+    if (includedTools.length === 0) {
+      getLogger().error('No tools match the provided filters');
+      process.exit(1);
+    }
+    return includedTools;
+  } catch (error) {
+    getLogger().error({ error }, 'Error filtering tools');
+    process.exit(1);
+  }
+}

package/src/instructions.ts

@@ -0,0 +1,59 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import fs from 'fs/promises';
+import { getLogger } from './logger';
+
+const INSTRUCTIONS_CACHE_TTL_MS = 15 * 60 * 1000; // 15 minutes
+
+interface InstructionsCacheEntry {
+  fetchedInstructions: string;
+  fetchedAt: number;
+}
+
+const instructionsCache = new Map<string, InstructionsCacheEntry>();
+
+export async function getInstructions({
+  stainlessApiKey,
+  customInstructionsPath,
+}: {
+  stainlessApiKey?: string | undefined;
+  customInstructionsPath?: string | undefined;
+}): Promise<string> {
+  const now = Date.now();
+  const cacheKey = customInstructionsPath ?? stainlessApiKey ?? '';
+  const cached = instructionsCache.get(cacheKey);
+
+  if (cached && now - cached.fetchedAt <= INSTRUCTIONS_CACHE_TTL_MS) {
+    return cached.fetchedInstructions;
+  }
+
+  // Evict stale entries so the cache doesn't grow unboundedly.
+  for (const [key, entry] of instructionsCache) {
+    if (now - entry.fetchedAt > INSTRUCTIONS_CACHE_TTL_MS) {
+      instructionsCache.delete(key);
+    }
+  }
+
+  let fetchedInstructions: string;
+
+  if (customInstructionsPath) {
+    fetchedInstructions = await fetchLatestInstructionsFromFile(customInstructionsPath);
+  } else {
+    fetchedInstructions =
+      '\n  This is the augno MCP server.\n\n  Available tools:\n  - search_docs: Search SDK documentation to find the right methods and parameters.\n  - execute: Run TypeScript code against a pre-authenticated SDK client. Define an async run(client) function.\n\n  Workflow:\n  - If unsure about the API, call search_docs first.\n  - Write complete solutions in a single execute call when possible. For large datasets, use API filters to narrow results or paginate within a single execute block.\n  - If execute returns an error, read the error and fix your code rather than retrying the same approach.\n  - Variables do not persist between execute calls. Return or log all data you need.\n  - Individual HTTP requests to the API have a 30-second timeout. If a request times out, try a smaller query or add filters.\n  - Code execution has a total timeout of approximately 5 minutes. If your code times out, simplify it or break it into smaller steps.\n  ';
+    fetchedInstructions +=
+      '\nThis MCP server wraps the Augno API (production management for SMB\nmanufacturers). Use the code tool to call the API by writing TypeScript\nagainst the Augno SDK. Authenticate with an Augno API key as a Bearer\ntoken; set the active account with the Augno-Account header when\noperating across multiple accounts.\n';
+  }
+
+  instructionsCache.set(cacheKey, { fetchedInstructions, fetchedAt: now });
+  return fetchedInstructions;
+}
+
+async function fetchLatestInstructionsFromFile(path: string): Promise<string> {
+  try {
+    return await fs.readFile(path, 'utf-8');
+  } catch (error) {
+    getLogger().error({ error, path }, 'Error fetching instructions from file');
+    throw error;
+  }
+}

package/src/logger.ts

@@ -0,0 +1,28 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { pino, type Level, type Logger } from 'pino';
+import pretty from 'pino-pretty';
+
+let _logger: Logger | undefined;
+
+export function configureLogger({ level, pretty: usePretty }: { level: Level; pretty: boolean }): void {
+  _logger = pino(
+    {
+      level,
+      timestamp: pino.stdTimeFunctions.isoTime,
+      formatters: {
+        level(label) {
+          return { level: label };
+        },
+      },
+    },
+    usePretty ? pretty({ colorize: true, levelFirst: true, destination: 2 }) : process.stderr,
+  );
+}
+
+export function getLogger(): Logger {
+  if (!_logger) {
+    throw new Error('Logger has not been configured. Call configureLogger() before using the logger.');
+  }
+  return _logger;
+}