@xano/developer-mcp 1.0.58 → 1.0.59

package/README.md

@@ -339,12 +339,16 @@ Retrieves XanoScript programming language documentation with context-aware suppo
 | `topic` | string | No | Specific documentation topic to retrieve |
 | `file_path` | string | No | File path being edited for context-aware docs (e.g., `api/users/create_post.xs`) |
 | `mode` | string | No | `full` (default), `quick_reference` for compact syntax reference, or `index` for topic listing with sizes |
+| `tier` | string | No | Pre-packaged documentation tier for context-limited models: `survival` (~800 tokens) or `working` (~3500 tokens). Overrides topic/file_path/mode when set |
+| `max_tokens` | number | No | Maximum estimated token budget. Loads topics in priority order until budget is reached. Helps prevent context overflow for small-window models |
 | `exclude_topics` | string[] | No | Topic names to exclude from `file_path` results (e.g., topics already loaded) |
 
 **Available Topics:**
 
 | Topic | Description |
 |-------|-------------|
+| `survival` | Minimal syntax survival kit (~3KB, ~800 tokens) for models with <16K context |
+| `working` | Complete working reference (~12KB, ~3500 tokens) for models with 16-64K context |
 | `readme` | XanoScript overview, workspace structure, and quick reference |
 | `essentials` | Common patterns, quick reference, and common mistakes to avoid |
 | `syntax` | Expressions, operators, and filters for all XanoScript code |
@@ -387,6 +391,12 @@ Retrieves XanoScript programming language documentation with context-aware suppo
 // Get overview
 xanoscript_docs()
 
+// Get survival kit for small context models (~800 tokens)
+xanoscript_docs({ tier: "survival" })
+
+// Get working reference for medium context models (~3500 tokens)
+xanoscript_docs({ tier: "working" })
+
 // Get essentials (recommended first stop)
 xanoscript_docs({ topic: "essentials" })
 
@@ -396,6 +406,9 @@ xanoscript_docs({ topic: "functions" })
 // Discover available topics with sizes
 xanoscript_docs({ mode: "index" })
 
+// Budget-aware: load docs up to token limit
+xanoscript_docs({ file_path: "api/users/create_post.xs", max_tokens: 2000 })
+
 // Context-aware: get all docs relevant to file being edited
 xanoscript_docs({ file_path: "api/users/create_post.xs" })
 
@@ -516,6 +529,8 @@ The server also exposes XanoScript documentation as MCP resources for direct acc
 
 | Resource URI | Description |
 |--------------|-------------|
+| `xanoscript://docs/survival` | Minimal syntax survival kit (~800 tokens) |
+| `xanoscript://docs/working` | Complete working reference (~3500 tokens) |
 | `xanoscript://docs/readme` | Overview and quick reference |
 | `xanoscript://docs/essentials` | Common patterns, quick reference, and common mistakes to avoid |
 | `xanoscript://docs/syntax` | Expressions, operators, and filters |

package/dist/tools/index.d.ts

@@ -118,6 +118,15 @@ export declare const toolDefinitions: ({
                 enum: string[];
                 description: string;
             };
+            tier: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+            max_tokens: {
+                type: string;
+                description: string;
+            };
             exclude_topics: {
                 type: string;
                 items: {

package/dist/tools/xanoscript_docs.d.ts

@@ -76,6 +76,15 @@ export declare const xanoscriptDocsToolDefinition: {
                 enum: string[];
                 description: string;
             };
+            tier: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+            max_tokens: {
+                type: string;
+                description: string;
+            };
             exclude_topics: {
                 type: string;
                 items: {

package/dist/tools/xanoscript_docs.js

@@ -92,6 +92,15 @@ export function xanoscriptDocs(args) {
 export function xanoscriptDocsTool(args) {
     try {
         const docsPath = getXanoscriptDocsPath();
+        // Tier mode: return single content block for pre-built tiers
+        if (args?.tier) {
+            const result = xanoscriptDocs(args);
+            return {
+                success: true,
+                data: result.documentation,
+                structuredContent: { tier: args.tier, documentation: result.documentation },
+            };
+        }
         // file_path mode: return structured multi-content (one block per topic)
         if (args?.file_path) {
             const version = getXanoscriptDocsVersion(docsPath);
@@ -139,8 +148,10 @@ export const xanoscriptDocsToolDefinition = {
     name: "xanoscript_docs",
     description: "Get XanoScript programming language documentation for AI code generation. " +
         "Call without parameters for overview (README). " +
+        "For context-limited models: use tier='survival' (~800 tokens) or tier='working' (~3500 tokens). " +
         "Use 'topic' for specific documentation, or 'file_path' for context-aware docs based on the file you're editing. " +
         "Use mode='quick_reference' for compact syntax reference (recommended for context efficiency). " +
+        "Use max_tokens to limit documentation size to fit your context budget. " +
         "file_path mode defaults to 'quick_reference' to reduce context size; use mode='full' to get complete docs.",
     annotations: {
         readOnlyHint: true,
@@ -175,6 +186,22 @@ export const xanoscriptDocsToolDefinition = {
                     "Use 'quick_reference' to save context window space when you just need a reminder. " +
                     "Default: 'full' for topic mode, 'quick_reference' for file_path mode.",
             },
+            tier: {
+                type: "string",
+                enum: ["survival", "working"],
+                description: "Pre-packaged documentation tier for context-limited models. " +
+                    "'survival' (~3KB, ~800 tokens): minimum syntax to write valid XanoScript. " +
+                    "'working' (~12KB, ~3500 tokens): complete reference for common tasks. " +
+                    "Overrides topic/file_path/mode when set. " +
+                    "Use 'survival' for models with <16K context, 'working' for 16-64K context.",
+            },
+            max_tokens: {
+                type: "number",
+                description: "Maximum estimated token budget for documentation. " +
+                    "When used with file_path, loads topics in priority order until budget is reached. " +
+                    "Helps prevent context overflow for small-window models. " +
+                    "Estimate: 1KB of docs ≈ 250 tokens.",
+            },
             exclude_topics: {
                 type: "array",
                 items: { type: "string" },

package/dist/xanoscript.d.ts

@@ -8,11 +8,14 @@ export interface DocConfig {
     file: string;
     applyTo: string[];
     description: string;
+    priority?: number;
 }
 export interface XanoscriptDocsArgs {
     topic?: string;
     file_path?: string;
     mode?: "full" | "quick_reference" | "index";
+    tier?: "survival" | "working";
+    max_tokens?: number;
     exclude_topics?: string[];
 }
 export declare const XANOSCRIPT_DOCS_V2: Record<string, DocConfig>;
@@ -26,7 +29,8 @@ export declare function clearDocsCache(): void;
  */
 export declare function getDocsForFilePath(filePath: string): string[];
 /**
- * Extract just the Quick Reference section from a doc
+ * Extract the Quick Reference section plus critical sections
+ * (Common Mistakes, Decision/Choosing trees) from a doc.
  */
 export declare function extractQuickReference(content: string, topic: string): string;
 /**

package/dist/xanoscript.js

@@ -18,6 +18,7 @@ function buildDocsConfig() {
             file: topic.file,
             applyTo: topic.applyTo,
             description: topic.description,
+            priority: topic.priority,
         };
     }
     return config;
@@ -69,7 +70,8 @@ export function getDocsForFilePath(filePath) {
     return matches;
 }
 /**
- * Extract just the Quick Reference section from a doc
+ * Extract the Quick Reference section plus critical sections
+ * (Common Mistakes, Decision/Choosing trees) from a doc.
  */
 export function extractQuickReference(content, topic) {
     const lines = content.split("\n");
@@ -83,9 +85,21 @@ export function extractQuickReference(content, topic) {
     let endIdx = lines.findIndex((l, i) => i > startIdx && l.startsWith("## "));
     if (endIdx === -1)
         endIdx = lines.length;
+    const sections = [lines.slice(startIdx, endIdx).join("\n")];
+    // Also extract Common Mistakes and Decision/Choosing sections if present
+    const bonusSections = ["## Common Mistakes", "## Choosing", "## Decision"];
+    for (const sectionName of bonusSections) {
+        const sIdx = lines.findIndex((l) => l.startsWith(sectionName));
+        if (sIdx !== -1 && sIdx !== startIdx) {
+            let eIdx = lines.findIndex((l, i) => i > sIdx && l.startsWith("## "));
+            if (eIdx === -1)
+                eIdx = lines.length;
+            sections.push(lines.slice(sIdx, eIdx).join("\n"));
+        }
+    }
     // Include topic header for context
     const header = `# ${topic}\n\n`;
-    return header + lines.slice(startIdx, endIdx).join("\n");
+    return header + sections.join("\n\n---\n\n");
 }
 /**
  * Get the documentation version from the version.json file
@@ -109,7 +123,13 @@ export function getXanoscriptDocsVersion(docsPath) {
  */
 export function readXanoscriptDocsV2(docsPath, args) {
     const version = getXanoscriptDocsVersion(docsPath);
-    // Index mode: return compact topic listing with byte sizes
+    // Tier mode: return pre-built documentation tier
+    if (args?.tier) {
+        const tierFile = args.tier === "survival" ? "survival.md" : "working.md";
+        const content = cachedReadFile(join(docsPath, tierFile));
+        return `${content}\n\n---\nDocumentation version: ${version}`;
+    }
+    // Index mode: return compact topic listing with byte sizes and token estimates
     if (args?.mode === "index") {
         const rows = Object.entries(XANOSCRIPT_DOCS_V2).map(([name, config]) => {
             let size;
@@ -120,7 +140,8 @@ export function readXanoscriptDocsV2(docsPath, args) {
                 size = 0;
             }
             const sizeKb = (size / 1024).toFixed(1);
-            return `| ${name} | ${config.description} | ${sizeKb} KB |`;
+            const estTokens = Math.ceil(size / 4);
+            return `| ${name} | ${config.description} | ${sizeKb} KB | ~${estTokens} |`;
         });
         return [
             `# XanoScript Documentation Index`,
@@ -128,11 +149,12 @@ export function readXanoscriptDocsV2(docsPath, args) {
             `Version: ${version}`,
             `Topics: ${rows.length}`,
             ``,
-            `| Topic | Description | Size |`,
-            `|-------|-------------|------|`,
+            `| Topic | Description | Size | Est. Tokens |`,
+            `|-------|-------------|------|-------------|`,
             ...rows,
             ``,
             `Use topic='<name>' to load a specific topic. Use mode='quick_reference' for compact output.`,
+            `Use tier='survival' (~800 tokens) or tier='working' (~3500 tokens) for context-limited models.`,
         ].join("\n");
     }
     // Default to quick_reference for file_path mode (loads many topics),
@@ -150,6 +172,27 @@ export function readXanoscriptDocsV2(docsPath, args) {
         if (args.exclude_topics && args.exclude_topics.length > 0) {
             topics = topics.filter((t) => !args.exclude_topics.includes(t));
         }
+        // Budget-aware loading: sort by priority and stop when budget is exceeded
+        if (args.max_tokens) {
+            let tokenBudget = args.max_tokens;
+            const sortedTopics = [...topics].sort((a, b) => {
+                const pa = XANOSCRIPT_DOCS_V2[a]?.priority ?? 99;
+                const pb = XANOSCRIPT_DOCS_V2[b]?.priority ?? 99;
+                return pa - pb;
+            });
+            const filteredTopics = [];
+            for (const t of sortedTopics) {
+                const config = XANOSCRIPT_DOCS_V2[t];
+                const content = cachedReadFile(join(docsPath, config.file));
+                const topicContent = mode === "quick_reference" ? extractQuickReference(content, t) : content;
+                const estimatedTokens = Math.ceil(topicContent.length / 4);
+                if (tokenBudget - estimatedTokens < 0 && filteredTopics.length > 0)
+                    break;
+                filteredTopics.push(t);
+                tokenBudget -= estimatedTokens;
+            }
+            topics = filteredTopics;
+        }
         if (topics.length === 0) {
             throw new Error(`No documentation found for file pattern: ${args.file_path}\n\nAvailable topics: ${Object.keys(XANOSCRIPT_DOCS_V2).join(", ")}`);
         }
@@ -185,6 +228,27 @@ export function readXanoscriptDocsStructured(docsPath, args) {
     if (args.exclude_topics && args.exclude_topics.length > 0) {
         topics = topics.filter((t) => !args.exclude_topics.includes(t));
     }
+    // Budget-aware loading
+    if (args.max_tokens) {
+        let tokenBudget = args.max_tokens;
+        const sortedTopics = [...topics].sort((a, b) => {
+            const pa = XANOSCRIPT_DOCS_V2[a]?.priority ?? 99;
+            const pb = XANOSCRIPT_DOCS_V2[b]?.priority ?? 99;
+            return pa - pb;
+        });
+        const filteredTopics = [];
+        for (const t of sortedTopics) {
+            const config = XANOSCRIPT_DOCS_V2[t];
+            const content = cachedReadFile(join(docsPath, config.file));
+            const topicContent = mode === "quick_reference" ? extractQuickReference(content, t) : content;
+            const estimatedTokens = Math.ceil(topicContent.length / 4);
+            if (tokenBudget - estimatedTokens < 0 && filteredTopics.length > 0)
+                break;
+            filteredTopics.push(t);
+            tokenBudget -= estimatedTokens;
+        }
+        topics = filteredTopics;
+    }
     if (topics.length === 0) {
         throw new Error(`No documentation found for file pattern: ${args.file_path}\n\nAvailable topics: ${Object.keys(XANOSCRIPT_DOCS_V2).join(", ")}`);
     }

package/dist/xanoscript.test.js

@@ -9,6 +9,8 @@ describe("xanoscript module", () => {
     describe("XANOSCRIPT_DOCS_V2", () => {
         it("should have all expected topics", () => {
             const expectedTopics = [
+                "survival",
+                "working",
                 "readme",
                 "essentials",
                 "syntax",
@@ -310,7 +312,7 @@ Even more content.
         it("should throw when all topics are excluded via exclude_topics", () => {
             expect(() => readXanoscriptDocsV2(DOCS_PATH, {
                 file_path: "branch.xs",
-                exclude_topics: ["syntax", "essentials", "debugging", "branch"],
+                exclude_topics: ["syntax", "essentials", "debugging", "branch", "survival", "working"],
             })).toThrow("No documentation found");
         });
         it("should throw for invalid docs path", () => {
@@ -321,7 +323,7 @@ Even more content.
             expect(result).toContain("# XanoScript Documentation Index");
             expect(result).toContain("Version:");
             expect(result).toContain("Topics:");
-            expect(result).toContain("| Topic | Description | Size |");
+            expect(result).toContain("| Topic | Description | Size | Est. Tokens |");
             // Should contain some known topics
             expect(result).toContain("| syntax |");
             expect(result).toContain("| essentials |");
@@ -404,7 +406,7 @@ Even more content.
         it("should throw when all topics are excluded", () => {
             expect(() => readXanoscriptDocsStructured(DOCS_PATH, {
                 file_path: "branch.xs",
-                exclude_topics: ["syntax", "essentials", "debugging", "branch"],
+                exclude_topics: ["syntax", "essentials", "debugging", "branch", "survival", "working"],
             })).toThrow("No documentation found");
         });
         it("should use quick_reference mode by default", () => {

package/dist/xanoscript_docs/README.md

@@ -178,6 +178,15 @@ This includes:
 
 Use `xanoscript_docs({ topic: "<topic>" })` to retrieve documentation.
 
+### Tiers (for context-limited models)
+
+| Topic      | Description                                                  | Size |
+| ---------- | ------------------------------------------------------------ | ---- |
+| `survival` | Minimal syntax survival kit for models with <16K context     | ~3KB (~800 tokens) |
+| `working`  | Complete working reference for models with 16-64K context    | ~12KB (~3500 tokens) |
+
+Use `xanoscript_docs({ tier: "survival" })` or `xanoscript_docs({ tier: "working" })`.
+
 ### Core Language
 
 | Topic        | Description                                          | Key Sections |
@@ -245,46 +254,3 @@ Use `xanoscript_docs({ topic: "<topic>" })` to retrieve documentation.
 | `performance` | Performance optimization best practices                      | Caching, Query Optimization |
 | `security`    | Security best practices for authentication and authorization | Auth Patterns, Token Handling |
 
----
-
-## Example Implementations
-
-Common integration patterns you can reference:
-
-### External API Integrations
-- **OpenAI/ChatGPT**: Use `api.request` with POST to `/v1/chat/completions`
-- **Stripe**: Use `api.request` with form-encoded params for payments
-- **SendGrid/Resend**: Use `api.request` or `util.send_email` for emails
-- **Slack/Discord**: Use `api.request` with webhook URLs
-- **Twilio**: Use `api.request` with Basic auth for SMS
-
-### Common Pattern: API Integration Function
-
-```xs
-function "call_external_api" {
-  input {
-    text endpoint
-    object payload
-  }
-  stack {
-    api.request {
-      url = $env.API_BASE_URL ~ $input.endpoint
-      method = "POST"
-      params = $input.payload
-      headers = [
-        "Content-Type: application/json",
-        "Authorization: Bearer " ~ $env.API_KEY
-      ]
-      timeout = 30
-    } as $api_result
-
-    precondition ($api_result.response.status >= 200 && $api_result.response.status < 300) {
-      error_type = "standard"
-      error = "API error: " ~ ($api_result.response.status|to_text)
-    }
-  }
-  response = $api_result.response.result
-}
-```
-
-For more patterns, see `xanoscript_docs({ topic: "essentials" })` or `xanoscript_docs({ topic: "integrations" })`.

package/dist/xanoscript_docs/addons.md

@@ -252,8 +252,6 @@ addon/
 1. **Keep addons focused** - One purpose per addon
 2. **Use input parameters** - Make addons reusable
 3. **Use appropriate return types** - `list`, `single`, `count`, `exists`
-4. **Limit nested queries** - Avoid N+1 query patterns
-5. **Document inputs** - Add descriptions to input fields
 
 ---
 

package/dist/xanoscript_docs/agents.md

@@ -290,35 +290,6 @@ agent "Code Reviewer" {
 }
 ```
 
-### Multi-Tool Research Agent
-```xs
-agent "Research Assistant" {
-  canonical = "research-v1"
-  llm = {
-    type: "openai"
-    api_key: "{{ $env.OPENAI_API_KEY }}"
-    model: "gpt-5"
-    system_prompt: """
-      You are a research assistant. Use your tools to:
-      1. Search for relevant information
-      2. Analyze data
-      3. Compile findings into clear summaries
-      Always cite your sources.
-    """
-    prompt: "Research topic: {{ $args.topic }}"
-    max_steps: 10
-    temperature: 0.5
-    reasoning_effort: "high"
-  }
-  tools = [
-    { name: "web_search" },
-    { name: "fetch_article" },
-    { name: "analyze_data" },
-    { name: "save_findings" }
-  ]
-}
-```
-
 ---
 
 ## External MCP Tools
@@ -407,12 +378,8 @@ agent "Research Agent" {
 ## Best Practices
 
 1. **Clear system prompts** - Define persona, capabilities, and constraints
-2. **Use appropriate temperature** - Low for factual, higher for creative
-3. **Limit max_steps** - Prevent infinite loops (3-10 typical)
-4. **Don't repeat tool descriptions** - They're auto-injected
-5. **Use environment variables** - Never hardcode API keys
-6. **Test with xano-free first** - Free for development
-7. **Validate external MCP servers** - Check server_details before using
+2. **Limit max_steps** - Prevent infinite loops (3-10 typical)
+3. **Don't repeat tool descriptions** - They're auto-injected; use environment variables for API keys
 
 ---
 

package/dist/xanoscript_docs/apis.md

@@ -440,12 +440,9 @@ When using `return = { type: "list", paging: {...} }`:
 
 ## Best Practices
 
-1. **RESTful design** - Use appropriate HTTP methods for operations
-2. **Consistent naming** - Use lowercase, hyphens for multi-word paths
-3. **Authenticate writes** - Always require auth for POST/PATCH/DELETE
-4. **Paginate lists** - Never return unbounded result sets
-5. **Group by resource** - Organize endpoints in logical api groups
-6. **Use specific canonicals** - Prefix canonicals to avoid instance-level collisions (e.g., `myapp-users` not `users`)
+1. **Use specific canonicals** - Prefix canonicals to avoid instance-level collisions (e.g., `myapp-users` not `users`)
+2. **Authenticate writes** - Always require `auth` for POST/PATCH/DELETE endpoints
+3. **Paginate lists** - Use `return = { type: "list", paging: {...} }` to avoid unbounded result sets
 
 ---
 

package/dist/xanoscript_docs/branch.md

@@ -236,5 +236,3 @@ project/
 1. **Use descriptive colors** - Green for production, blue for development, yellow for staging
 2. **Limit production history** - Excessive history impacts performance and storage
 3. **Apply security middleware in production** - Rate limiting, auth checks, audit logging
-4. **Disable middleware history in production** - Reduces noise and storage
-5. **Enable full history in development** - Aids debugging and testing

package/dist/xanoscript_docs/database.md

@@ -628,13 +628,9 @@ try_catch {
 
 ## Best Practices
 
-1. **Use db.query for searches** - Flexible filtering and pagination
-2. **Use db.get for single lookups** - Simpler than db.query with single return
-3. **Use db.patch for dynamic updates** - Accepts variable data
-4. **Use transactions for atomicity** - Ensure all-or-nothing operations
-5. **Use null-safe operators** - `==?` for optional filters
-6. **Use bulk operations for batch processing** - More efficient than loops
-7. **Handle deadlocks gracefully** - Implement retry logic for concurrent writes
+1. **Use null-safe operators** - `==?` for optional filters avoids manual null checks
+2. **Use bulk operations for batch processing** - More efficient than loops with individual db calls
+3. **Use transactions for atomicity** - Ensure all-or-nothing operations across multiple tables
 
 ---