@llamaindex/llama-cloud-mcp 1.6.0 → 1.7.0

package/src/instructions.ts

@@ -0,0 +1,75 @@
+// 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/llamacloud-prod',
+    {
+      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 = `
+      This is the llamacloud-prod 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 = `
+    If needed, you can get the current time by executing Date.now().
+
+    ${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;
+}

package/src/options.ts

@@ -8,19 +8,24 @@ import { readEnv } from './util';
 
 export type CLIOptions = McpOptions & {
   debug: boolean;
+  logFormat: 'json' | 'pretty';
   transport: 'stdio' | 'http';
   port: number | undefined;
   socket: string | undefined;
 };
 
 export type McpOptions = {
+  includeCodeTool?: boolean | undefined;
   includeDocsTools?: boolean | undefined;
   stainlessApiKey?: string | undefined;
   codeAllowHttpGets?: boolean | undefined;
   codeAllowedMethods?: string[] | undefined;
   codeBlockedMethods?: string[] | undefined;
+  codeExecutionMode: McpCodeExecutionMode;
 };
 
+export type McpCodeExecutionMode = 'stainless-sandbox' | 'local';
+
 export function parseCLIOptions(): CLIOptions {
   const opts = yargs(hideBin(process.argv))
     .option('code-allow-http-gets', {
@@ -40,7 +45,19 @@ export function parseCLIOptions(): CLIOptions {
       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('code-execution-mode', {
+      type: 'string',
+      choices: ['stainless-sandbox', 'local'],
+      default: 'stainless-sandbox',
+      description:
+        "Where to run code execution in code tool; 'stainless-sandbox' will execute code in Stainless-hosted sandboxes whereas 'local' will execute code locally on the MCP server machine.",
+    })
     .option('debug', { type: 'boolean', description: 'Enable debug logging' })
+    .option('log-format', {
+      type: 'string',
+      choices: ['json', 'pretty'],
+      description: 'Format for log output; defaults to json unless tty is detected',
+    })
     .option('no-tools', {
       type: 'string',
       array: true,
@@ -82,18 +99,26 @@ export function parseCLIOptions(): CLIOptions {
     : argv.tools?.includes(toolType) ? true
     : undefined;
 
+  const includeCodeTool = shouldIncludeToolType('code');
   const includeDocsTools = shouldIncludeToolType('docs');
 
   const transport = argv.transport as 'stdio' | 'http';
+  const logFormat =
+    argv.logFormat ? (argv.logFormat as 'json' | 'pretty')
+    : process.stderr.isTTY ? 'pretty'
+    : 'json';
 
   return {
+    ...(includeCodeTool !== undefined && { includeCodeTool }),
     ...(includeDocsTools !== undefined && { includeDocsTools }),
     debug: !!argv.debug,
     stainlessApiKey: argv.stainlessApiKey,
     codeAllowHttpGets: argv.codeAllowHttpGets,
     codeAllowedMethods: argv.codeAllowedMethods,
     codeBlockedMethods: argv.codeBlockedMethods,
+    codeExecutionMode: argv.codeExecutionMode as McpCodeExecutionMode,
     transport,
+    logFormat,
     port: argv.port,
     socket: argv.socket,
   };
@@ -118,12 +143,19 @@ export function parseQueryOptions(defaultOptions: McpOptions, query: unknown): M
   const queryObject = typeof query === 'string' ? qs.parse(query) : query;
   const queryOptions = QueryOptions.parse(queryObject);
 
+  let codeTool: boolean | undefined =
+    queryOptions.no_tools && queryOptions.no_tools?.includes('code') ? false
+    : queryOptions.tools?.includes('code') ? true
+    : defaultOptions.includeCodeTool;
+
   let docsTools: boolean | undefined =
     queryOptions.no_tools && queryOptions.no_tools?.includes('docs') ? false
     : queryOptions.tools?.includes('docs') ? true
     : defaultOptions.includeDocsTools;
 
   return {
+    ...(codeTool !== undefined && { includeCodeTool: codeTool }),
     ...(docsTools !== undefined && { includeDocsTools: docsTools }),
+    codeExecutionMode: defaultOptions.codeExecutionMode,
   };
 }

package/src/server.ts

@@ -11,52 +11,16 @@ import { ClientOptions } from '@llamaindex/llama-cloud';
 import LlamaCloud from '@llamaindex/llama-cloud';
 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';
-import { readEnv } from './util';
-
-async function getInstructions(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/llamacloud-prod',
-    {
-      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 llamacloud-prod 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 (stainlessApiKey: string | undefined) =>
   new McpServer(
     {
       name: 'llamaindex_llama_cloud_api',
-      version: '1.6.0',
+      version: '1.7.0',
     },
     {
       instructions: await getInstructions(stainlessApiKey),
@@ -91,14 +55,32 @@ export async function initMcpServer(params: {
     error: logAtLevel('error'),
   };
 
-  let client = new LlamaCloud({
-    logger,
-    ...params.clientOptions,
-    defaultHeaders: {
-      ...params.clientOptions?.defaultHeaders,
-      'X-Stainless-MCP': 'true',
-    },
-  });
+  let _client: LlamaCloud | undefined;
+  let _clientError: Error | undefined;
+  let _logLevel: 'debug' | 'info' | 'warn' | 'error' | 'off' | undefined;
+
+  const getClient = (): LlamaCloud => {
+    if (_clientError) throw _clientError;
+    if (!_client) {
+      try {
+        _client = new LlamaCloud({
+          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]));
@@ -116,6 +98,21 @@ export async function initMcpServer(params: {
       throw new Error(`Unknown tool: ${name}`);
     }
 
+    let client: LlamaCloud;
+    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: {
@@ -128,24 +125,29 @@ export async function initMcpServer(params: {
 
   server.setRequestHandler(SetLevelRequestSchema, async (request) => {
     const { level } = request.params;
+    let logLevel: 'debug' | 'info' | 'warn' | 'error' | 'off';
     switch (level) {
       case 'debug':
-        client = client.withOptions({ logLevel: 'debug' });
+        logLevel = 'debug';
         break;
       case 'info':
-        client = client.withOptions({ logLevel: 'info' });
+        logLevel = 'info';
         break;
       case 'notice':
       case 'warning':
-        client = client.withOptions({ logLevel: 'warn' });
+        logLevel = 'warn';
         break;
       case 'error':
-        client = client.withOptions({ logLevel: 'error' });
+        logLevel = 'error';
         break;
       default:
-        client = client.withOptions({ logLevel: 'off' });
+        logLevel = 'off';
         break;
     }
+    _logLevel = logLevel;
+    if (_client) {
+      _client = _client.withOptions({ logLevel });
+    }
     return {};
   });
 }
@@ -154,11 +156,16 @@ export async function initMcpServer(params: {
  * 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),
-    }),
-  ];
+  const includedTools = [];
+
+  if (options?.includeCodeTool ?? true) {
+    includedTools.push(
+      codeTool({
+        blockedMethods: blockedMethodsForCodeTool(options),
+        codeExecutionMode: options?.codeExecutionMode ?? 'stainless-sandbox',
+      }),
+    );
+  }
   if (options?.includeDocsTools ?? true) {
     includedTools.push(docsSearchTool);
   }

package/src/stdio.ts

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

package/stdio.d.mts.map

@@ -1 +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"}
+{"version":3,"file":"stdio.d.mts","sourceRoot":"","sources":["src/stdio.ts"],"names":[],"mappings":"OACO,EAAE,UAAU,EAAE;AAIrB,eAAO,MAAM,iBAAiB,GAAU,YAAY,UAAU,kBAQ7D,CAAC"}

package/stdio.d.ts.map

@@ -1 +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"}
+{"version":3,"file":"stdio.d.ts","sourceRoot":"","sources":["src/stdio.ts"],"names":[],"mappings":"OACO,EAAE,UAAU,EAAE;AAIrB,eAAO,MAAM,iBAAiB,GAAU,YAAY,UAAU,kBAQ7D,CAAC"}

package/stdio.js

@@ -3,12 +3,13 @@ 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 logger_1 = require("./logger.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');
+    (0, logger_1.getLogger)().info('MCP Server running on stdio');
 };
 exports.launchStdioServer = launchStdioServer;
 //# sourceMappingURL=stdio.js.map

package/stdio.js.map

@@ -1 +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"}
+{"version":3,"file":"stdio.js","sourceRoot":"","sources":["src/stdio.ts"],"names":[],"mappings":";;;AAAA,wEAAiF;AAEjF,wCAAuD;AACvD,wCAAqC;AAE9B,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,IAAA,kBAAS,GAAE,CAAC,IAAI,CAAC,6BAA6B,CAAC,CAAC;AAClD,CAAC,CAAC;AARW,QAAA,iBAAiB,qBAQ5B"}

package/stdio.mjs

@@ -1,10 +1,11 @@
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { initMcpServer, newMcpServer } from "./server.mjs";
+import { getLogger } from "./logger.mjs";
 export const launchStdioServer = async (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');
+    getLogger().info('MCP Server running on stdio');
 };
 //# sourceMappingURL=stdio.mjs.map

package/stdio.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"stdio.mjs","sourceRoot":"","sources":["src/stdio.ts"],"names":[],"mappings":"OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C;OAEzE,EAAE,aAAa,EAAE,YAAY,EAAE;AAEtC,MAAM,CAAC,MAAM,iBAAiB,GAAG,KAAK,EAAE,UAAsB,EAAE,EAAE;IAChE,MAAM,MAAM,GAAG,MAAM,YAAY,CAAC,UAAU,CAAC,eAAe,CAAC,CAAC;IAE9D,MAAM,aAAa,CAAC,EAAE,MAAM,EAAE,UAAU,EAAE,eAAe,EAAE,UAAU,CAAC,eAAe,EAAE,CAAC,CAAC;IAEzF,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAChC,OAAO,CAAC,KAAK,CAAC,6BAA6B,CAAC,CAAC;AAC/C,CAAC,CAAC"}
+{"version":3,"file":"stdio.mjs","sourceRoot":"","sources":["src/stdio.ts"],"names":[],"mappings":"OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C;OAEzE,EAAE,aAAa,EAAE,YAAY,EAAE;OAC/B,EAAE,SAAS,EAAE;AAEpB,MAAM,CAAC,MAAM,iBAAiB,GAAG,KAAK,EAAE,UAAsB,EAAE,EAAE;IAChE,MAAM,MAAM,GAAG,MAAM,YAAY,CAAC,UAAU,CAAC,eAAe,CAAC,CAAC;IAE9D,MAAM,aAAa,CAAC,EAAE,MAAM,EAAE,UAAU,EAAE,eAAe,EAAE,UAAU,CAAC,eAAe,EAAE,CAAC,CAAC;IAEzF,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAChC,SAAS,EAAE,CAAC,IAAI,CAAC,6BAA6B,CAAC,CAAC;AAClD,CAAC,CAAC"}