@metronome/mcp 2.2.0 → 3.4.1

package/src/http.ts

@@ -2,16 +2,18 @@
 
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
-
+import { ClientOptions } from '@metronome/sdk';
 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';
+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 = ({
+const newServer = async ({
   clientOptions,
-  mcpOptions: defaultMcpOptions,
+  mcpOptions,
   req,
   res,
 }: {
@@ -19,43 +21,21 @@ const newServer = ({
   mcpOptions: McpOptions;
   req: express.Request;
   res: express.Response;
-}): McpServer | null => {
-  const server = newMcpServer();
+}): Promise<McpServer | null> => {
+  const stainlessApiKey = getStainlessApiKey(req, mcpOptions);
+  const server = await newMcpServer(stainlessApiKey);
 
-  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;
-  }
+  const authOptions = parseClientAuthHeaders(req, false);
 
-  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;
-  }
+  await initMcpServer({
+    server: server,
+    mcpOptions: mcpOptions,
+    clientOptions: {
+      ...clientOptions,
+      ...authOptions,
+    },
+    stainlessApiKey: stainlessApiKey,
+  });
 
   return server;
 };
@@ -63,14 +43,11 @@ const newServer = ({
 const post =
   (options: { clientOptions: ClientOptions; mcpOptions: McpOptions }) =>
   async (req: express.Request, res: express.Response) => {
-    const server = newServer({ ...options, req, res });
+    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({
-      // Stateless server
-      sessionIdGenerator: undefined,
-    });
-    await server.connect(transport);
+    const transport = new StreamableHTTPServerTransport();
+    await server.connect(transport as any);
     await transport.handleRequest(req, res, req.body);
   };
 
@@ -94,17 +71,64 @@ const del = async (req: express.Request, res: express.Response) => {
   });
 };
 
+const redactHeaders = (headers: Record<string, any>) => {
+  const hiddenHeaders = /auth|cookie|key|token/i;
+  const filtered = { ...headers };
+  Object.keys(filtered).forEach((key) => {
+    if (hiddenHeaders.test(key)) {
+      filtered[key] = '[REDACTED]';
+    }
+  });
+  return filtered;
+};
+
 export const streamableHTTPApp = ({
   clientOptions = {},
-  mcpOptions = {},
+  mcpOptions,
 }: {
   clientOptions?: ClientOptions;
-  mcpOptions?: McpOptions;
+  mcpOptions: McpOptions;
 }): express.Express => {
   const app = express();
   app.set('query parser', 'extended');
   app.use(express.json());
+  app.use(
+    pinoHttp({
+      logger: getLogger(),
+      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);
@@ -112,16 +136,24 @@ export const streamableHTTPApp = ({
   return app;
 };
 
-export const launchStreamableHTTPServer = async (options: McpOptions, port: number | string | undefined) => {
-  const app = streamableHTTPApp({ mcpOptions: options });
+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') {
-    console.error(`MCP Server running on streamable HTTP at ${address}`);
+    logger.info(`MCP Server running on streamable HTTP at ${address}`);
   } else if (address !== null) {
-    console.error(`MCP Server running on streamable HTTP on port ${address.port}`);
+    logger.info(`MCP Server running on streamable HTTP on port ${address.port}`);
   } else {
-    console.error(`MCP Server running on streamable HTTP on port ${port}`);
+    logger.info(`MCP Server running on streamable HTTP on port ${port}`);
   }
 };

package/src/index.ts

@@ -1,24 +1,24 @@
 #!/usr/bin/env node
 
 import { selectTools } from './server';
-import { Endpoint, endpoints } from './tools';
 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',
+  });
 
-  if (options.list) {
-    listAllTools();
-    return;
-  }
-
-  const selectedTools = await selectToolsOrError(endpoints, options);
+  const selectedTools = await selectToolsOrError(options);
 
-  console.error(
-    `MCP Server starting with ${selectedTools.length} tools:`,
-    selectedTools.map((e) => e.tool.name),
+  getLogger().info(
+    { tools: selectedTools.map((e) => e.tool.name) },
+    `MCP Server starting with ${selectedTools.length} tools`,
   );
 
   switch (options.transport) {
@@ -26,14 +26,18 @@ async function main() {
       await launchStdioServer(options);
       break;
     case 'http':
-      await launchStreamableHTTPServer(options, options.port ?? options.socket);
+      await launchStreamableHTTPServer({
+        mcpOptions: options,
+        port: options.socket ?? options.port,
+      });
       break;
   }
 }
 
 if (require.main === module) {
   main().catch((error) => {
-    console.error('Fatal error in main():', error);
+    // Logger might not be initialized yet
+    console.error('Fatal error in main()', error);
     process.exit(1);
   });
 }
@@ -42,67 +46,22 @@ function parseOptionsOrError() {
   try {
     return parseCLIOptions();
   } catch (error) {
-    console.error('Error parsing options:', error);
+    // Logger is initialized after options, so use console.error here
+    console.error('Error parsing options', error);
     process.exit(1);
   }
 }
 
-async function selectToolsOrError(endpoints: Endpoint[], options: McpOptions): Promise<Endpoint[]> {
+async function selectToolsOrError(options: McpOptions): Promise<McpTool[]> {
   try {
-    const includedTools = await selectTools(endpoints, options);
+    const includedTools = selectTools(options);
     if (includedTools.length === 0) {
-      console.error('No tools match the provided filters.');
+      getLogger().error('No tools match the provided filters');
       process.exit(1);
     }
     return includedTools;
   } catch (error) {
-    if (error instanceof Error) {
-      console.error('Error filtering tools:', error.message);
-    } else {
-      console.error('Error filtering tools:', error);
-    }
+    getLogger().error({ error }, 'Error filtering tools');
     process.exit(1);
   }
 }
-
-function listAllTools() {
-  if (endpoints.length === 0) {
-    console.log('No tools available.');
-    return;
-  }
-  console.log('Available tools:\n');
-
-  // Group endpoints by resource
-  const resourceGroups = new Map<string, typeof endpoints>();
-
-  for (const endpoint of endpoints) {
-    const resource = endpoint.metadata.resource;
-    if (!resourceGroups.has(resource)) {
-      resourceGroups.set(resource, []);
-    }
-    resourceGroups.get(resource)!.push(endpoint);
-  }
-
-  // Sort resources alphabetically
-  const sortedResources = Array.from(resourceGroups.keys()).sort();
-
-  // Display hierarchically by resource
-  for (const resource of sortedResources) {
-    console.log(`Resource: ${resource}`);
-
-    const resourceEndpoints = resourceGroups.get(resource)!;
-    // Sort endpoints by tool name
-    resourceEndpoints.sort((a, b) => a.tool.name.localeCompare(b.tool.name));
-
-    for (const endpoint of resourceEndpoints) {
-      const {
-        tool,
-        metadata: { operation, tags },
-      } = endpoint;
-
-      console.log(`  - ${tool.name} (${operation}) ${tags.length > 0 ? `tags: ${tags.join(', ')}` : ''}`);
-      console.log(`    Description: ${tool.description}`);
-    }
-    console.log('');
-  }
-}

package/src/instructions.ts

@@ -0,0 +1,65 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { readEnv } from './util';
+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>();
+
+// Periodically evict stale entries so the cache doesn't grow unboundedly.
+const _cacheCleanupInterval = setInterval(() => {
+  const now = Date.now();
+  for (const [key, entry] of instructionsCache) {
+    if (now - entry.fetchedAt > INSTRUCTIONS_CACHE_TTL_MS) {
+      instructionsCache.delete(key);
+    }
+  }
+}, INSTRUCTIONS_CACHE_TTL_MS);
+
+// Don't keep the process alive just for cleanup.
+_cacheCleanupInterval.unref();
+
+export async function getInstructions(stainlessApiKey: string | undefined): Promise<string> {
+  const cacheKey = stainlessApiKey ?? '';
+  const cached = instructionsCache.get(cacheKey);
+
+  if (cached && Date.now() - cached.fetchedAt <= INSTRUCTIONS_CACHE_TTL_MS) {
+    return cached.fetchedInstructions;
+  }
+
+  const fetchedInstructions = await fetchLatestInstructions(stainlessApiKey);
+  instructionsCache.set(cacheKey, { fetchedInstructions, fetchedAt: Date.now() });
+  return fetchedInstructions;
+}
+
+async function fetchLatestInstructions(stainlessApiKey: string | undefined): Promise<string> {
+  // Setting the stainless API key is optional, but may be required
+  // to authenticate requests to the Stainless API.
+  const response = await fetch(
+    readEnv('CODE_MODE_INSTRUCTIONS_URL') ?? 'https://api.stainless.com/api/ai/instructions/metronome',
+    {
+      method: 'GET',
+      headers: { ...(stainlessApiKey && { Authorization: stainlessApiKey }) },
+    },
+  );
+
+  let instructions: string | undefined;
+  if (!response.ok) {
+    getLogger().warn(
+      'Warning: failed to retrieve MCP server instructions. Proceeding with default instructions...',
+    );
+
+    instructions =
+      '\n  This is the metronome 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  ';
+  }
+
+  instructions ??= ((await response.json()) as { instructions: string }).instructions;
+
+  return instructions;
+}

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;
+}