@xano/developer-mcp 1.0.51 → 1.0.53

package/dist/cli_docs/index.d.ts

@@ -26,6 +26,12 @@ export declare function handleCliDocs(args: CliDocsArgs): string;
  */
 export declare const cliDocsToolDefinition: {
     name: string;
+    annotations: {
+        readOnlyHint: boolean;
+        destructiveHint: boolean;
+        idempotentHint: boolean;
+        openWorldHint: boolean;
+    };
     description: string;
     inputSchema: {
         type: string;

package/dist/cli_docs/index.js

@@ -59,6 +59,12 @@ export function handleCliDocs(args) {
  */
 export const cliDocsToolDefinition = {
     name: "cli_docs",
+    annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+    },
     description: `Get documentation for the Xano CLI. Use this to understand how to use the CLI for local development, code sync, and XanoScript execution.
 
 ## Topics

package/dist/meta_api_docs/index.d.ts

@@ -26,6 +26,12 @@ export declare function handleMetaApiDocs(args: MetaApiDocsArgs): string;
  */
 export declare const metaApiDocsToolDefinition: {
     name: string;
+    annotations: {
+        readOnlyHint: boolean;
+        destructiveHint: boolean;
+        idempotentHint: boolean;
+        openWorldHint: boolean;
+    };
     description: string;
     inputSchema: {
         type: string;

package/dist/meta_api_docs/index.js

@@ -77,6 +77,12 @@ export function handleMetaApiDocs(args) {
  */
 export const metaApiDocsToolDefinition = {
     name: "meta_api_docs",
+    annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+    },
     description: `Get documentation for Xano's Meta API. Use this to understand how to programmatically manage Xano workspaces, databases, APIs, functions, agents, and more.
 
 ## Topics

package/dist/tools/index.d.ts

@@ -42,6 +42,12 @@ export { validateXanoscriptToolDefinition, xanoscriptDocsToolDefinition, mcpVers
  */
 export declare const toolDefinitions: ({
     name: string;
+    annotations: {
+        readOnlyHint: boolean;
+        destructiveHint: boolean;
+        idempotentHint: boolean;
+        openWorldHint: boolean;
+    };
     description: string;
     inputSchema: {
         type: string;
@@ -50,6 +56,12 @@ export declare const toolDefinitions: ({
     };
 } | {
     name: string;
+    annotations: {
+        readOnlyHint: boolean;
+        destructiveHint: boolean;
+        idempotentHint: boolean;
+        openWorldHint: boolean;
+    };
     description: string;
     inputSchema: {
         type: string;

package/dist/tools/mcp_version.d.ts

@@ -36,6 +36,12 @@ export declare function mcpVersion(): McpVersionResult;
 export declare function mcpVersionTool(): ToolResult;
 export declare const mcpVersionToolDefinition: {
     name: string;
+    annotations: {
+        readOnlyHint: boolean;
+        destructiveHint: boolean;
+        idempotentHint: boolean;
+        openWorldHint: boolean;
+    };
     description: string;
     inputSchema: {
         type: string;

package/dist/tools/mcp_version.js

@@ -84,6 +84,12 @@ export function mcpVersionTool() {
 // =============================================================================
 export const mcpVersionToolDefinition = {
     name: "mcp_version",
+    annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+    },
     description: "Get the current version of the Xano Developer MCP server. " +
         "Returns the version string from package.json.",
     inputSchema: {

package/dist/tools/validate_xanoscript.d.ts

@@ -109,6 +109,12 @@ export declare function validateXanoscript(args: ValidateXanoscriptArgs): Valida
 export declare function validateXanoscriptTool(args: ValidateXanoscriptArgs): ToolResult;
 export declare const validateXanoscriptToolDefinition: {
     name: string;
+    annotations: {
+        readOnlyHint: boolean;
+        destructiveHint: boolean;
+        idempotentHint: boolean;
+        openWorldHint: boolean;
+    };
     description: string;
     inputSchema: {
         type: string;

package/dist/tools/validate_xanoscript.js

@@ -388,6 +388,12 @@ export function validateXanoscriptTool(args) {
 // =============================================================================
 export const validateXanoscriptToolDefinition = {
     name: "validate_xanoscript",
+    annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+    },
     description: "Validate XanoScript code for syntax errors. Supports multiple input methods:\n" +
         "- code: Raw XanoScript code as a string\n" +
         "- file_path: Path to a single .xs file (easier than escaping code!)\n" +

package/dist/tools/xanoscript_docs.d.ts

@@ -50,11 +50,18 @@ export declare function xanoscriptDocsTool(args?: XanoscriptDocsArgs): ToolResul
 export declare const xanoscriptDocsToolDefinition: {
     name: string;
     description: string;
+    annotations: {
+        readOnlyHint: boolean;
+        destructiveHint: boolean;
+        idempotentHint: boolean;
+        openWorldHint: boolean;
+    };
     inputSchema: {
         type: string;
         properties: {
             topic: {
                 type: string;
+                enum: string[];
                 description: string;
             };
             file_path: {

package/dist/tools/xanoscript_docs.js

@@ -7,7 +7,7 @@
 import { readFileSync } from "fs";
 import { dirname, join } from "path";
 import { fileURLToPath } from "url";
-import { readXanoscriptDocsV2, getTopicDescriptions, } from "../xanoscript.js";
+import { readXanoscriptDocsV2, getTopicNames, getTopicDescriptions, } from "../xanoscript.js";
 // =============================================================================
 // Path Resolution
 // =============================================================================
@@ -105,11 +105,18 @@ export const xanoscriptDocsToolDefinition = {
         "Call without parameters for overview (README). " +
         "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 cheatsheet (recommended for context efficiency).",
+    annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+    },
     inputSchema: {
         type: "object",
         properties: {
             topic: {
                 type: "string",
+                enum: getTopicNames(),
                 description: "Documentation topic to retrieve. Call without any parameters to get the README overview. " +
                     "Example: topic='syntax' for language syntax, topic='database' for database operations, topic='types' for type system.\n\n" +
                     "Available topics:\n" + getTopicDescriptions(),

package/dist/xanoscript.js

@@ -243,47 +243,38 @@ export function getXanoscriptDocsVersion(docsPath) {
 export function readXanoscriptDocsV2(docsPath, args) {
     const mode = args?.mode || "full";
     const version = getXanoscriptDocsVersion(docsPath);
-    try {
-        // Default: return README
-        if (!args?.topic && !args?.file_path) {
-            const readme = readFileSync(join(docsPath, "README.md"), "utf-8");
-            return `${readme}\n\n---\nDocumentation version: ${version}`;
-        }
-        // Context-aware: return docs matching file pattern
-        if (args?.file_path) {
-            const topics = getDocsForFilePath(args.file_path);
-            if (topics.length === 0) {
-                return `No documentation found for file pattern: ${args.file_path}\n\nAvailable topics: ${Object.keys(XANOSCRIPT_DOCS_V2).join(", ")}`;
-            }
-            const docs = topics.map((t) => {
-                const config = XANOSCRIPT_DOCS_V2[t];
-                const content = readFileSync(join(docsPath, config.file), "utf-8");
-                return mode === "quick_reference"
-                    ? extractQuickReference(content, t)
-                    : content;
-            });
-            const header = `# XanoScript Documentation for: ${args.file_path}\n\nMatched topics: ${topics.join(", ")}\nMode: ${mode}\nVersion: ${version}\n\n---\n\n`;
-            return header + docs.join("\n\n---\n\n");
+    // Default: return README
+    if (!args?.topic && !args?.file_path) {
+        const readme = readFileSync(join(docsPath, "README.md"), "utf-8");
+        return `${readme}\n\n---\nDocumentation version: ${version}`;
+    }
+    // Context-aware: return docs matching file pattern
+    if (args?.file_path) {
+        const topics = getDocsForFilePath(args.file_path);
+        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(", ")}`);
         }
-        // Topic-based: return specific doc
-        if (args?.topic) {
-            const config = XANOSCRIPT_DOCS_V2[args.topic];
-            if (!config) {
-                const availableTopics = Object.keys(XANOSCRIPT_DOCS_V2).join(", ");
-                return `Error: Unknown topic "${args.topic}".\n\nAvailable topics: ${availableTopics}`;
-            }
+        const docs = topics.map((t) => {
+            const config = XANOSCRIPT_DOCS_V2[t];
             const content = readFileSync(join(docsPath, config.file), "utf-8");
-            const doc = mode === "quick_reference"
-                ? extractQuickReference(content, args.topic)
+            return mode === "quick_reference"
+                ? extractQuickReference(content, t)
                 : content;
-            return `${doc}\n\n---\nDocumentation version: ${version}`;
-        }
-        return "Error: Invalid parameters";
+        });
+        const header = `# XanoScript Documentation for: ${args.file_path}\n\nMatched topics: ${topics.join(", ")}\nMode: ${mode}\nVersion: ${version}\n\n---\n\n`;
+        return header + docs.join("\n\n---\n\n");
     }
-    catch (error) {
-        const errorMessage = error instanceof Error ? error.message : String(error);
-        return `Error reading XanoScript documentation: ${errorMessage}`;
+    // Topic-based: return specific doc
+    const config = XANOSCRIPT_DOCS_V2[args.topic];
+    if (!config) {
+        const availableTopics = Object.keys(XANOSCRIPT_DOCS_V2).join(", ");
+        throw new Error(`Unknown topic "${args.topic}".\n\nAvailable topics: ${availableTopics}`);
     }
+    const content = readFileSync(join(docsPath, config.file), "utf-8");
+    const doc = mode === "quick_reference"
+        ? extractQuickReference(content, args.topic)
+        : content;
+    return `${doc}\n\n---\nDocumentation version: ${version}`;
 }
 /**
  * Get available topic names

package/dist/xanoscript.test.js

@@ -126,7 +126,7 @@ describe("xanoscript module", () => {
             expect(result).toContain("branch");
         });
         it("should match workspace.xs", () => {
-            const result = getDocsForFilePath("workspace.xs");
+            const result = getDocsForFilePath("workspace/workspace.xs");
             expect(result).toContain("syntax");
             expect(result).toContain("workspace");
         });
@@ -236,10 +236,8 @@ Even more content.
             const result = readXanoscriptDocsV2(DOCS_PATH, { topic: "syntax" });
             expect(result).toContain("Documentation version:");
         });
-        it("should return error for unknown topic", () => {
-            const result = readXanoscriptDocsV2(DOCS_PATH, { topic: "nonexistent" });
-            expect(result).toContain('Error: Unknown topic "nonexistent"');
-            expect(result).toContain("Available topics:");
+        it("should throw for unknown topic", () => {
+            expect(() => readXanoscriptDocsV2(DOCS_PATH, { topic: "nonexistent" })).toThrow('Unknown topic "nonexistent"');
         });
         it("should return context-aware docs for file_path", () => {
             const result = readXanoscriptDocsV2(DOCS_PATH, {
@@ -272,11 +270,8 @@ Even more content.
             });
             expect(quickResult).toContain("Mode: quick_reference");
         });
-        it("should return error for invalid docs path", () => {
-            const result = readXanoscriptDocsV2("/nonexistent/path", {
-                topic: "syntax",
-            });
-            expect(result).toContain("Error reading XanoScript documentation:");
+        it("should throw for invalid docs path", () => {
+            expect(() => readXanoscriptDocsV2("/nonexistent/path", { topic: "syntax" })).toThrow();
         });
     });
     describe("getTopicNames", () => {

package/dist/xanoscript_docs/cheatsheet.md

@@ -6,7 +6,9 @@ applyTo: "**/*.xs"
 
 > **Purpose:** Quick reference for the 20 most common XanoScript patterns. For detailed documentation, use `xanoscript_docs({ topic: "<topic>" })`.
 
-## Variable Declaration
+## Quick Reference
+
+### Variable Declaration
 
 ```xs
 var $name { value = "initial" }
@@ -15,7 +17,7 @@ var $items { value = [] }
 var $data { value = { key: "value" } }
 ```
 
-## Conditionals
+### Conditionals
 
 ```xs
 conditional {
@@ -33,7 +35,7 @@ conditional {
 
 > **Note:** Use `elseif` (one word), not `else if`.
 
-## Switch
+### Switch
 
 ```xs
 switch ($input.status) {
@@ -51,7 +53,7 @@ switch ($input.status) {
 
 > **Note:** `break` goes **after** the closing `}` of each `case` block. The `default` case does not need `break`.
 
-## Loops
+### Loops
 
 ```xs
 // For each loop
@@ -81,7 +83,7 @@ var $names { value = $items|map:$$.name }
 var $active { value = $items|filter:$$.is_active }
 ```
 
-## Database CRUD
+### Database CRUD
 
 ```xs
 // Get single record by field
@@ -113,7 +115,7 @@ db.edit "user" {
 db.del "user" { field_name = "id", field_value = $input.user_id }
 ```
 
-## API Requests
+### API Requests
 
 ```xs
 api.request {
@@ -133,7 +135,7 @@ api.request {
 // $api_result.response.headers → Response headers
 ```
 
-## Error Handling
+### Error Handling
 
 ```xs
 // Precondition (stops execution if false)
@@ -159,7 +161,7 @@ throw {
 }
 ```
 
-## Error Types
+### Error Types
 
 | Type | HTTP Status | Use Case |
 |------|-------------|----------|
@@ -168,7 +170,7 @@ throw {
 | `notfound` | 404 | Resource doesn't exist |
 | `standard` | 500 | General errors |
 
-## Common Filters
+### Common Filters
 
 ```xs
 // String
@@ -210,7 +212,7 @@ $num|round:2                  // Round to 2 decimals
 $num|abs                      // Absolute value
 ```
 
-## Authentication Check
+### Authentication Check
 
 ```xs
 precondition ($auth.id != null) {
@@ -219,7 +221,7 @@ precondition ($auth.id != null) {
 }
 ```
 
-## Function Call
+### Function Call
 
 ```xs
 function.run "my_function" {
@@ -227,7 +229,7 @@ function.run "my_function" {
 } as $result
 ```
 
-## String Concatenation
+### String Concatenation
 
 ```xs
 // Basic
@@ -237,7 +239,7 @@ var $msg { value = "Hello, " ~ $input.name ~ "!" }
 var $msg { value = ($status|to_text) ~ ": " ~ ($data|json_encode) }
 ```
 
-## Common Type Names
+### Common Type Names
 
 | Use This | Not This |
 |----------|----------|
@@ -247,11 +249,11 @@ var $msg { value = ($status|to_text) ~ ": " ~ ($data|json_encode) }
 | `decimal` | float, number |
 | `type[]` | array, list |
 
-## Reserved Variables (Cannot Use)
+### Reserved Variables (Cannot Use)
 
 `$response`, `$output`, `$input`, `$auth`, `$env`, `$db`, `$this`, `$result`, `$index`
 
-## Input Block Syntax
+### Input Block Syntax
 
 `?` after the **type** = nullable, `?` after the **variable name** = optional (not required).
 

package/dist/xanoscript_docs/debugging.md

@@ -113,7 +113,7 @@ debug.stop
 function "process_order" {
   input { int order_id }
   stack {
-    var $trace_id { value = |uuid }
+    security.create_uuid as $trace_id
 
     debug.log {
       label = "TRACE_START"

package/dist/xanoscript_docs/quickstart.md

@@ -10,6 +10,36 @@ Essential patterns for XanoScript development. Use this as a quick reference for
 
 ## Quick Reference
 
+### Variable Access Rules
+
+**Inputs must use `$input.fieldname` — no shorthand exists.**
+
+Input fields declared in the `input {}` block are only accessible via the `$input` prefix. You cannot reference them as bare variables.
+
+```xs
+input {
+  text name
+  int age
+}
+
+// ❌ Wrong — $name is not defined; inputs live on $input
+var $greeting { value = "Hello, " ~ $name }
+
+// ✅ Correct
+var $greeting { value = "Hello, " ~ $input.name }
+var $is_adult { value = $input.age >= 18 }
+```
+
+**Stack variables have an optional `$var.` prefix — both forms are identical.**
+
+```xs
+var $total { value = 100 }
+
+// ✅ Both are the same thing
+$var.total       // explicit prefix form
+$total           // shorthand form (no prefix)
+```
+
 ### Reserved Variable Names
 
 These variable names are reserved and cannot be used:
@@ -268,7 +298,7 @@ precondition ($input.email|contains:"@") {
 | `db.query` | Filtered list | `db.query "users" { where = $db.users.active == true } as $users` |
 | `db.add` | Insert | `db.add "users" { data = { name: "John" } } as $new` |
 | `db.edit` | Update | `db.edit "users" { field_name = "id" field_value = 1 data = { name: "Jane" } }` |
-| `db.delete` | Delete | `db.delete "users" { field_name = "id" field_value = 1 }` |
+| `db.del` | Delete | `db.del "users" { field_name = "id" field_value = 1 }` |
 
 > **Full reference:** See `xanoscript_docs({ topic: "database" })` for joins, bulk operations, transactions, and more.
 
@@ -293,9 +323,11 @@ var $data {
 ### 4. Loop Through Array
 
 ```xs
-// Using each
-each ($items as $item) {
-  debug.log { value = $item.name }
+// Using foreach
+foreach ($items) {
+  each as $item {
+    debug.log { value = $item.name }
+  }
 }
 
 // Using map filter

package/dist/xanoscript_docs/security.md

@@ -96,7 +96,7 @@ function "refresh_auth" {
     } as $new_token
 
     // Rotate refresh token
-    var $new_refresh { value = |uuid }
+    security.create_uuid as $new_refresh
 
     db.edit "refresh_token" {
       field_name = "id"
@@ -120,7 +120,7 @@ function "refresh_auth" {
 function "create_session" {
   input { int user_id }
   stack {
-    var $session_id { value = |uuid }
+    security.create_uuid as $session_id
 
     db.add "session" {
       data = {

package/dist/xanoscript_docs/syntax.md

@@ -85,6 +85,29 @@ Working with...
 
 ## Quick Reference
 
+### Variable Access Prefixes
+
+| Prefix | Applies to | Shorthand? |
+|--------|-----------|------------|
+| `$input.field` | Input parameters | No — prefix always required |
+| `$var.field` | Stack variables | Yes — `$field` is identical |
+| `$auth.field` | Auth context | No |
+| `$env.NAME` | Environment variables | No |
+| `$db.table.field` | DB field refs (queries) | No |
+
+```xs
+// ❌ Wrong — input fields are NOT accessible as bare variables
+var $name { value = $name }      // undefined; inputs live on $input
+
+// ✅ Correct — always use $input for input fields
+var $name { value = $input.name }
+
+// ✅ Both are valid for stack variables
+var $total { value = 0 }
+$var.total      // explicit
+$total          // shorthand — same thing
+```
+
 ### Operators
 | Category | Operators |
 |----------|-----------|

package/dist/xanoscript_docs/unit-testing.md

@@ -107,34 +107,34 @@ function "add" {
 ### Value Assertions
 
 ```xs
-# Equality
+// Equality
 expect.to_equal ($response.status) { value = "active" }
 expect.to_not_equal ($response.status) { value = "deleted" }
 
-# Boolean
+// Boolean
 expect.to_be_true ($response.is_active)
 expect.to_be_false ($response.is_deleted)
 
-# Null
+// Null
 expect.to_be_null ($response.deleted_at)
 expect.to_not_be_null ($response.created_at)
 
-# Defined
+// Defined
 expect.to_be_defined ($response.id)
 expect.to_not_be_defined ($response.optional_field)
 
-# Empty
+// Empty
 expect.to_be_empty ($response.errors)
 ```
 
 ### Comparison Assertions
 
 ```xs
-# Numeric comparisons
+// Numeric comparisons
 expect.to_be_greater_than ($response.total) { value = 100 }
 expect.to_be_less_than ($response.stock) { value = 10 }
 
-# Range
+// Range
 expect.to_be_within ($response.temperature) {
   min = 20
   max = 30
@@ -144,14 +144,14 @@ expect.to_be_within ($response.temperature) {
 ### String Assertions
 
 ```xs
-# Starts/ends with
+// Starts/ends with
 expect.to_start_with ($response.name) { value = "John" }
 expect.to_end_with ($response.file) { value = ".pdf" }
 
-# Contains
+// Contains
 expect.to_contain ($response.tags) { value = "featured" }
 
-# Regex match
+// Regex match
 expect.to_match ($response.phone) { value = "^\\+1\\d{10}$" }
 ```
 
@@ -165,13 +165,13 @@ expect.to_be_in_the_future ($response.expires_at)
 ### Error Assertions
 
 ```xs
-# Expects any error
+// Expects any error
 test "throws on invalid input" {
   input = { amount: -1 }
   expect.to_throw
 }
 
-# Expects specific error
+// Expects specific error
 test "throws validation error" {
   input = { amount: -1 }
   expect.to_throw { value = "InvalidInputError" }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xano/developer-mcp",
-  "version": "1.0.51",
+  "version": "1.0.53",
   "description": "MCP server and library for Xano development - XanoScript validation, Meta API, Run API, and CLI documentation",
   "type": "module",
   "main": "dist/lib.js",