@llamaindex/llama-cloud-mcp 1.7.0 → 2.0.0

package/src/docs-search-tool.ts

@@ -3,6 +3,7 @@
 import { Tool } from '@modelcontextprotocol/sdk/types.js';
 import { Metadata, McpRequestContext, asTextContentResult } from './types';
 import { getLogger } from './logger';
+import type { LocalDocsSearch } from './local-docs-search';
 
 export const metadata: Metadata = {
   resource: 'all',
@@ -13,7 +14,8 @@ export const metadata: Metadata = {
 
 export const tool: Tool = {
   name: 'search_docs',
-  description: 'Search for documentation for how to use the client to interact with the API.',
+  description:
+    'Search SDK documentation to find methods, parameters, and usage examples for interacting with the API. Use this before writing code when you need to discover the right approach.',
   inputSchema: {
     type: 'object',
     properties: {
@@ -42,13 +44,30 @@ export const tool: Tool = {
 const docsSearchURL =
   process.env['DOCS_SEARCH_URL'] || 'https://api.stainless.com/api/projects/llamacloud-prod/docs/search';
 
-export const handler = async ({
-  reqContext,
-  args,
-}: {
-  reqContext: McpRequestContext;
-  args: Record<string, unknown> | undefined;
-}) => {
+let _localSearch: LocalDocsSearch | undefined;
+
+export function setLocalSearch(search: LocalDocsSearch): void {
+  _localSearch = search;
+}
+
+async function searchLocal(args: Record<string, unknown>): Promise<unknown> {
+  if (!_localSearch) {
+    throw new Error('Local search not initialized');
+  }
+
+  const query = (args['query'] as string) ?? '';
+  const language = (args['language'] as string) ?? 'typescript';
+  const detail = (args['detail'] as string) ?? 'default';
+
+  return _localSearch.search({
+    query,
+    language,
+    detail,
+    maxResults: 5,
+  }).results;
+}
+
+async function searchRemote(args: Record<string, unknown>, reqContext: McpRequestContext): Promise<unknown> {
   const body = args as any;
   const query = new URLSearchParams(body).toString();
 
@@ -56,6 +75,10 @@ export const handler = async ({
   const result = await fetch(`${docsSearchURL}?${query}`, {
     headers: {
       ...(reqContext.stainlessApiKey && { Authorization: reqContext.stainlessApiKey }),
+      ...(reqContext.mcpSessionId && { 'x-stainless-mcp-session-id': reqContext.mcpSessionId }),
+      ...(reqContext.mcpClientInfo && {
+        'x-stainless-mcp-client-info': JSON.stringify(reqContext.mcpClientInfo),
+      }),
     },
   });
 
@@ -93,7 +116,23 @@ export const handler = async ({
     },
     'Got docs search result',
   );
-  return asTextContentResult(resultBody);
+  return resultBody;
+}
+
+export const handler = async ({
+  reqContext,
+  args,
+}: {
+  reqContext: McpRequestContext;
+  args: Record<string, unknown> | undefined;
+}) => {
+  const body = args ?? {};
+
+  if (_localSearch) {
+    return asTextContentResult(await searchLocal(body));
+  }
+
+  return asTextContentResult(await searchRemote(body, reqContext));
 };
 
 export default { metadata, tool, handler };

package/src/http.ts

@@ -23,18 +23,66 @@ const newServer = async ({
   res: express.Response;
 }): Promise<McpServer | null> => {
   const stainlessApiKey = getStainlessApiKey(req, mcpOptions);
-  const server = await newMcpServer(stainlessApiKey);
+  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');
+    }
+  }
+
   await initMcpServer({
     server: server,
-    mcpOptions: mcpOptions,
+    mcpOptions: effectiveMcpOptions,
     clientOptions: {
       ...clientOptions,
       ...authOptions,
     },
     stainlessApiKey: stainlessApiKey,
+    upstreamClientEnvs,
+    mcpSessionId: (req as any).mcpSessionId,
+    mcpClientInfo:
+      typeof req.body?.params?.clientInfo?.name === 'string' ?
+        { name: req.body.params.clientInfo.name, version: String(req.body.params.clientInfo.version ?? '') }
+      : undefined,
   });
 
   return server;
@@ -72,7 +120,7 @@ const del = async (req: express.Request, res: express.Response) => {
 };
 
 const redactHeaders = (headers: Record<string, any>) => {
-  const hiddenHeaders = /auth|cookie|key|token/i;
+  const hiddenHeaders = /auth|cookie|key|token|x-stainless-mcp-client-envs/i;
   const filtered = { ...headers };
   Object.keys(filtered).forEach((key) => {
     if (hiddenHeaders.test(key)) {
@@ -92,6 +140,17 @@ export const streamableHTTPApp = ({
   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(),

package/src/instructions.ts

@@ -1,5 +1,6 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
+import fs from 'fs/promises';
 import { readEnv } from './util';
 import { getLogger } from './logger';
 
@@ -12,33 +13,50 @@ interface InstructionsCacheEntry {
 
 const instructionsCache = new Map<string, InstructionsCacheEntry>();
 
-// Periodically evict stale entries so the cache doesn't grow unboundedly.
-const _cacheCleanupInterval = setInterval(() => {
+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);
     }
   }
-}, 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);
+  let fetchedInstructions: string;
 
-  if (cached && Date.now() - cached.fetchedAt <= INSTRUCTIONS_CACHE_TTL_MS) {
-    return cached.fetchedInstructions;
+  if (customInstructionsPath) {
+    fetchedInstructions = await fetchLatestInstructionsFromFile(customInstructionsPath);
+  } else {
+    fetchedInstructions = await fetchLatestInstructionsFromApi(stainlessApiKey);
   }
 
-  const fetchedInstructions = await fetchLatestInstructions(stainlessApiKey);
-  instructionsCache.set(cacheKey, { fetchedInstructions, fetchedAt: Date.now() });
+  instructionsCache.set(cacheKey, { fetchedInstructions, fetchedAt: now });
   return fetchedInstructions;
 }
 
-async function fetchLatestInstructions(stainlessApiKey: string | undefined): Promise<string> {
+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;
+  }
+}
+
+async function fetchLatestInstructionsFromApi(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(
@@ -55,21 +73,11 @@ async function fetchLatestInstructions(stainlessApiKey: string | undefined): Pro
       '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 =
+      '\n  This is the llamacloud-prod 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;
-  instructions = `
-    If needed, you can get the current time by executing Date.now().
-
-    ${instructions}
-  `;
 
   return instructions;
 }