@llamaindex/llama-cloud-mcp 1.8.0 → 2.1.0

package/instructions.mjs

@@ -1,30 +1,42 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+import fs from 'fs/promises';
 import { readEnv } from "./util.mjs";
 import { getLogger } from "./logger.mjs";
 const INSTRUCTIONS_CACHE_TTL_MS = 15 * 60 * 1000; // 15 minutes
 const instructionsCache = new Map();
-// Periodically evict stale entries so the cache doesn't grow unboundedly.
-const _cacheCleanupInterval = setInterval(() => {
+export async function getInstructions({ stainlessApiKey, customInstructionsPath, }) {
     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) {
-    const cacheKey = stainlessApiKey ?? '';
-    const cached = instructionsCache.get(cacheKey);
-    if (cached && Date.now() - cached.fetchedAt <= INSTRUCTIONS_CACHE_TTL_MS) {
-        return cached.fetchedInstructions;
+    let fetchedInstructions;
+    if (customInstructionsPath) {
+        fetchedInstructions = await fetchLatestInstructionsFromFile(customInstructionsPath);
     }
-    const fetchedInstructions = await fetchLatestInstructions(stainlessApiKey);
-    instructionsCache.set(cacheKey, { fetchedInstructions, fetchedAt: Date.now() });
+    else {
+        fetchedInstructions = await fetchLatestInstructionsFromApi(stainlessApiKey);
+    }
+    instructionsCache.set(cacheKey, { fetchedInstructions, fetchedAt: now });
     return fetchedInstructions;
 }
-async function fetchLatestInstructions(stainlessApiKey) {
+async function fetchLatestInstructionsFromFile(path) {
+    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) {
     // 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', {
@@ -34,20 +46,10 @@ async function fetchLatestInstructions(stainlessApiKey) {
     let instructions;
     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 =
+            '\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()).instructions;
-    instructions = `
-    If needed, you can get the current time by executing Date.now().
-
-    ${instructions}
-  `;
     return instructions;
 }
 //# sourceMappingURL=instructions.mjs.map

package/instructions.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"instructions.mjs","sourceRoot":"","sources":["src/instructions.ts"],"names":[],"mappings":"AAAA,sFAAsF;OAE/E,EAAE,OAAO,EAAE;OACX,EAAE,SAAS,EAAE;AAEpB,MAAM,yBAAyB,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC,aAAa;AAO/D,MAAM,iBAAiB,GAAG,IAAI,GAAG,EAAkC,CAAC;AAEpE,0EAA0E;AAC1E,MAAM,qBAAqB,GAAG,WAAW,CAAC,GAAG,EAAE;IAC7C,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IACvB,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,iBAAiB,EAAE,CAAC;QAC7C,IAAI,GAAG,GAAG,KAAK,CAAC,SAAS,GAAG,yBAAyB,EAAE,CAAC;YACtD,iBAAiB,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAChC,CAAC;IACH,CAAC;AACH,CAAC,EAAE,yBAAyB,CAAC,CAAC;AAE9B,iDAAiD;AACjD,qBAAqB,CAAC,KAAK,EAAE,CAAC;AAE9B,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,eAAmC;IACvE,MAAM,QAAQ,GAAG,eAAe,IAAI,EAAE,CAAC;IACvC,MAAM,MAAM,GAAG,iBAAiB,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IAE/C,IAAI,MAAM,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,MAAM,CAAC,SAAS,IAAI,yBAAyB,EAAE,CAAC;QACzE,OAAO,MAAM,CAAC,mBAAmB,CAAC;IACpC,CAAC;IAED,MAAM,mBAAmB,GAAG,MAAM,uBAAuB,CAAC,eAAe,CAAC,CAAC;IAC3E,iBAAiB,CAAC,GAAG,CAAC,QAAQ,EAAE,EAAE,mBAAmB,EAAE,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;IAChF,OAAO,mBAAmB,CAAC;AAC7B,CAAC;AAED,KAAK,UAAU,uBAAuB,CAAC,eAAmC;IACxE,iEAAiE;IACjE,iDAAiD;IACjD,MAAM,QAAQ,GAAG,MAAM,KAAK,CAC1B,OAAO,CAAC,4BAA4B,CAAC,IAAI,+DAA+D,EACxG;QACE,MAAM,EAAE,KAAK;QACb,OAAO,EAAE,EAAE,GAAG,CAAC,eAAe,IAAI,EAAE,aAAa,EAAE,eAAe,EAAE,CAAC,EAAE;KACxE,CACF,CAAC;IAEF,IAAI,YAAgC,CAAC;IACrC,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;QACjB,SAAS,EAAE,CAAC,IAAI,CACd,8FAA8F,CAC/F,CAAC;QAEF,YAAY,GAAG;;;;;;KAMd,CAAC;IACJ,CAAC;IAED,YAAY,KAAM,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,CAA8B,CAAC,YAAY,CAAC;IACpF,YAAY,GAAG;;;MAGX,YAAY;GACf,CAAC;IAEF,OAAO,YAAY,CAAC;AACtB,CAAC"}
+{"version":3,"file":"instructions.mjs","sourceRoot":"","sources":["src/instructions.ts"],"names":[],"mappings":"AAAA,sFAAsF;OAE/E,EAAE,MAAM,aAAa;OACrB,EAAE,OAAO,EAAE;OACX,EAAE,SAAS,EAAE;AAEpB,MAAM,yBAAyB,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC,aAAa;AAO/D,MAAM,iBAAiB,GAAG,IAAI,GAAG,EAAkC,CAAC;AAEpE,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,EACpC,eAAe,EACf,sBAAsB,GAIvB;IACC,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IACvB,MAAM,QAAQ,GAAG,sBAAsB,IAAI,eAAe,IAAI,EAAE,CAAC;IACjE,MAAM,MAAM,GAAG,iBAAiB,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IAE/C,IAAI,MAAM,IAAI,GAAG,GAAG,MAAM,CAAC,SAAS,IAAI,yBAAyB,EAAE,CAAC;QAClE,OAAO,MAAM,CAAC,mBAAmB,CAAC;IACpC,CAAC;IAED,6DAA6D;IAC7D,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,iBAAiB,EAAE,CAAC;QAC7C,IAAI,GAAG,GAAG,KAAK,CAAC,SAAS,GAAG,yBAAyB,EAAE,CAAC;YACtD,iBAAiB,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAChC,CAAC;IACH,CAAC;IAED,IAAI,mBAA2B,CAAC;IAEhC,IAAI,sBAAsB,EAAE,CAAC;QAC3B,mBAAmB,GAAG,MAAM,+BAA+B,CAAC,sBAAsB,CAAC,CAAC;IACtF,CAAC;SAAM,CAAC;QACN,mBAAmB,GAAG,MAAM,8BAA8B,CAAC,eAAe,CAAC,CAAC;IAC9E,CAAC;IAED,iBAAiB,CAAC,GAAG,CAAC,QAAQ,EAAE,EAAE,mBAAmB,EAAE,SAAS,EAAE,GAAG,EAAE,CAAC,CAAC;IACzE,OAAO,mBAAmB,CAAC;AAC7B,CAAC;AAED,KAAK,UAAU,+BAA+B,CAAC,IAAY;IACzD,IAAI,CAAC;QACH,OAAO,MAAM,EAAE,CAAC,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IAC1C,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,SAAS,EAAE,CAAC,KAAK,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE,uCAAuC,CAAC,CAAC;QAC5E,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC;AAED,KAAK,UAAU,8BAA8B,CAAC,eAAmC;IAC/E,iEAAiE;IACjE,iDAAiD;IACjD,MAAM,QAAQ,GAAG,MAAM,KAAK,CAC1B,OAAO,CAAC,4BAA4B,CAAC,IAAI,+DAA+D,EACxG;QACE,MAAM,EAAE,KAAK;QACb,OAAO,EAAE,EAAE,GAAG,CAAC,eAAe,IAAI,EAAE,aAAa,EAAE,eAAe,EAAE,CAAC,EAAE;KACxE,CACF,CAAC;IAEF,IAAI,YAAgC,CAAC;IACrC,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;QACjB,SAAS,EAAE,CAAC,IAAI,CACd,8FAA8F,CAC/F,CAAC;QAEF,YAAY;YACV,g8BAAg8B,CAAC;IACr8B,CAAC;IAED,YAAY,KAAM,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,CAA8B,CAAC,YAAY,CAAC;IAEpF,OAAO,YAAY,CAAC;AACtB,CAAC"}

package/local-docs-search.d.mts

@@ -0,0 +1,28 @@
+type SearchResult = {
+    results: (string | Record<string, unknown>)[];
+};
+/**
+ * Self-contained local search engine backed by MiniSearch.
+ * Method data is embedded at SDK build time; prose documents
+ * can be loaded from an optional docs directory at runtime.
+ */
+export declare class LocalDocsSearch {
+    private methodIndex;
+    private proseIndex;
+    private constructor();
+    static create(opts?: {
+        docsDir?: string;
+    }): Promise<LocalDocsSearch>;
+    search(props: {
+        query: string;
+        language?: string;
+        detail?: string;
+        maxResults?: number;
+        maxLength?: number;
+    }): SearchResult;
+    private indexMethods;
+    private loadDocsDirectory;
+    private indexProse;
+}
+export {};
+//# sourceMappingURL=local-docs-search.d.mts.map

package/local-docs-search.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-docs-search.d.mts","sourceRoot":"","sources":["src/local-docs-search.ts"],"names":[],"mappings":"AA+CA,KAAK,YAAY,GAAG;IAClB,OAAO,EAAE,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EAAE,CAAC;CAC/C,CAAC;AAo1HF;;;;GAIG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,WAAW,CAAiC;IACpD,OAAO,CAAC,UAAU,CAAiC;IAEnD,OAAO;WAKM,MAAM,CAAC,IAAI,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,eAAe,CAAC;IAY1E,MAAM,CAAC,KAAK,EAAE;QACZ,KAAK,EAAE,MAAM,CAAC;QACd,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB,GAAG,YAAY;IA2EhB,OAAO,CAAC,YAAY;YAiBN,iBAAiB;IA4C/B,OAAO,CAAC,UAAU;CAgBnB"}

package/local-docs-search.d.ts

@@ -0,0 +1,28 @@
+type SearchResult = {
+    results: (string | Record<string, unknown>)[];
+};
+/**
+ * Self-contained local search engine backed by MiniSearch.
+ * Method data is embedded at SDK build time; prose documents
+ * can be loaded from an optional docs directory at runtime.
+ */
+export declare class LocalDocsSearch {
+    private methodIndex;
+    private proseIndex;
+    private constructor();
+    static create(opts?: {
+        docsDir?: string;
+    }): Promise<LocalDocsSearch>;
+    search(props: {
+        query: string;
+        language?: string;
+        detail?: string;
+        maxResults?: number;
+        maxLength?: number;
+    }): SearchResult;
+    private indexMethods;
+    private loadDocsDirectory;
+    private indexProse;
+}
+export {};
+//# sourceMappingURL=local-docs-search.d.ts.map

package/local-docs-search.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-docs-search.d.ts","sourceRoot":"","sources":["src/local-docs-search.ts"],"names":[],"mappings":"AA+CA,KAAK,YAAY,GAAG;IAClB,OAAO,EAAE,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EAAE,CAAC;CAC/C,CAAC;AAo1HF;;;;GAIG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,WAAW,CAAiC;IACpD,OAAO,CAAC,UAAU,CAAiC;IAEnD,OAAO;WAKM,MAAM,CAAC,IAAI,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,eAAe,CAAC;IAY1E,MAAM,CAAC,KAAK,EAAE;QACZ,KAAK,EAAE,MAAM,CAAC;QACd,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB,GAAG,YAAY;IA2EhB,OAAO,CAAC,YAAY;YAiBN,iBAAiB;IA4C/B,OAAO,CAAC,UAAU;CAgBnB"}