@xano/developer-mcp 1.0.24 → 1.0.26

package/README.md

@@ -30,6 +30,7 @@ This MCP server acts as a bridge between AI models and Xano's developer ecosyste
 
 - **Meta API Documentation** - Programmatically manage Xano workspaces, databases, APIs, functions, and more
 - **Run API Documentation** - Runtime execution, session management, and XanoScript execution
+- **CLI Documentation** - Command-line interface for local development, code sync, and execution
 - **XanoScript Documentation** - Language reference with context-aware docs based on file type
 - **Code Validation** - Syntax checking with the official XanoScript language server
 - **Workflow Guides** - Step-by-step guides for common development tasks
@@ -318,6 +319,48 @@ meta_api_docs({ topic: "api", detail_level: "examples", include_schemas: false }
 meta_api_docs({ topic: "workflows" })
 ```
 
+### 6. `cli_docs`
+
+Get documentation for the Xano CLI. The CLI is **optional but recommended** for local development workflows. Not all users will have it installed.
+
+- **npm:** https://www.npmjs.com/package/@xano/cli
+- **GitHub:** https://github.com/xano-inc/cli
+
+Use this tool to understand CLI commands for local development, code synchronization, and XanoScript execution.
+
+**Parameters:**
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `topic` | string | Yes | Documentation topic to retrieve |
+| `detail_level` | string | No | `overview`, `detailed` (default), or `examples` |
+
+**Available Topics:**
+
+| Topic | Description |
+|-------|-------------|
+| `start` | Getting started with the CLI - installation and setup |
+| `profile` | Profile management - credentials and multi-environment setup |
+| `workspace` | Workspace operations - pull/push code sync |
+| `function` | Function management - list, get, create, edit |
+| `run` | Run API commands - execute code, manage projects/sessions |
+| `static_host` | Static hosting - deploy frontend builds |
+| `integration` | CLI + Meta API integration guide - when to use each |
+
+**Examples:**
+```
+// Get CLI setup guide
+cli_docs({ topic: "start" })
+
+// Learn when to use CLI vs Meta API
+cli_docs({ topic: "integration" })
+
+// Get workspace sync commands
+cli_docs({ topic: "workspace", detail_level: "detailed" })
+
+// Profile management with examples
+cli_docs({ topic: "profile", detail_level: "examples" })
+```
+
 ## MCP Resources
 
 The server also exposes XanoScript documentation as MCP resources for direct access:
@@ -382,6 +425,11 @@ xano-developer-mcp/
 │   │   ├── format.ts                   # Documentation formatter
 │   │   ├── format.test.ts              # Tests for formatter
 │   │   └── topics/                     # Individual topic modules
+│   ├── cli_docs/                       # Xano CLI documentation
+│   │   ├── index.ts                    # CLI docs tool handler
+│   │   ├── types.ts                    # Type definitions
+│   │   ├── format.ts                   # Documentation formatter
+│   │   └── topics/                     # Individual topic modules
 │   └── xanoscript_docs/                # XanoScript language documentation
 │       ├── version.json
 │       ├── README.md
@@ -429,6 +477,8 @@ Xano Developer MCP Server
     │
     ├─► run_api_docs → Run API documentation for runtime execution
     │
+    ├─► cli_docs → CLI documentation for local development workflows
+    │
     ├─► mcp_version → Returns server version from package.json
     │
     └─► MCP Resources → Direct access to XanoScript documentation

package/dist/cli_docs/format.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Formatting utilities for CLI documentation
+ */
+import type { TopicDoc, CommandDoc, DetailLevel } from "./types.js";
+/**
+ * Format a command for display
+ */
+export declare function formatCommand(cmd: CommandDoc, detailed: boolean): string;
+/**
+ * Format complete documentation for a topic
+ */
+export declare function formatDocumentation(doc: TopicDoc, detailLevel: DetailLevel): string;

package/dist/cli_docs/format.js

@@ -0,0 +1,98 @@
+/**
+ * Formatting utilities for CLI documentation
+ */
+/**
+ * Format a command for display
+ */
+export function formatCommand(cmd, detailed) {
+    const lines = [];
+    lines.push(`### \`${cmd.name}\``);
+    lines.push(cmd.description);
+    lines.push("");
+    lines.push("```bash");
+    lines.push(cmd.usage);
+    lines.push("```");
+    if (detailed && cmd.flags && cmd.flags.length > 0) {
+        lines.push("");
+        lines.push("**Flags:**");
+        lines.push("| Flag | Type | Required | Description |");
+        lines.push("|------|------|----------|-------------|");
+        for (const flag of cmd.flags) {
+            const flagName = flag.short ? `-${flag.short}, --${flag.name}` : `--${flag.name}`;
+            const required = flag.required ? "Yes" : "No";
+            const desc = flag.default ? `${flag.description} (default: ${flag.default})` : flag.description;
+            lines.push(`| \`${flagName}\` | ${flag.type} | ${required} | ${desc} |`);
+        }
+    }
+    if (detailed && cmd.args && cmd.args.length > 0) {
+        lines.push("");
+        lines.push("**Arguments:**");
+        lines.push("| Argument | Required | Description |");
+        lines.push("|----------|----------|-------------|");
+        for (const arg of cmd.args) {
+            const required = arg.required ? "Yes" : "No";
+            lines.push(`| \`${arg.name}\` | ${required} | ${arg.description} |`);
+        }
+    }
+    if (cmd.examples && cmd.examples.length > 0) {
+        lines.push("");
+        lines.push("**Examples:**");
+        lines.push("```bash");
+        lines.push(cmd.examples.join("\n"));
+        lines.push("```");
+    }
+    return lines.join("\n");
+}
+/**
+ * Format complete documentation for a topic
+ */
+export function formatDocumentation(doc, detailLevel) {
+    const sections = [];
+    // Title and description
+    sections.push(`# ${doc.title}`);
+    sections.push("");
+    sections.push(doc.description);
+    // AI hints for overview/detailed
+    if (doc.ai_hints && (detailLevel === "overview" || detailLevel === "detailed")) {
+        sections.push("");
+        sections.push("## AI Usage Notes");
+        sections.push(doc.ai_hints);
+    }
+    // Commands
+    if (doc.commands && doc.commands.length > 0) {
+        sections.push("");
+        sections.push("## Commands");
+        const showDetailed = detailLevel === "detailed" || detailLevel === "examples";
+        for (const cmd of doc.commands) {
+            sections.push("");
+            sections.push(formatCommand(cmd, showDetailed));
+        }
+    }
+    // Workflows
+    if (doc.workflows && doc.workflows.length > 0 && detailLevel !== "overview") {
+        sections.push("");
+        sections.push("## Workflows");
+        for (const workflow of doc.workflows) {
+            sections.push("");
+            sections.push(`### ${workflow.name}`);
+            sections.push(workflow.description);
+            sections.push("");
+            workflow.steps.forEach((step, i) => {
+                sections.push(`${i + 1}. ${step}`);
+            });
+            if (workflow.example) {
+                sections.push("");
+                sections.push("```bash");
+                sections.push(workflow.example);
+                sections.push("```");
+            }
+        }
+    }
+    // Related topics
+    if (doc.related_topics && doc.related_topics.length > 0) {
+        sections.push("");
+        sections.push("## Related Topics");
+        sections.push(doc.related_topics.map(t => `- \`${t}\``).join("\n"));
+    }
+    return sections.join("\n");
+}

package/dist/cli_docs/index.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Xano CLI Documentation Index
+ *
+ * This module exports all documentation topics and provides
+ * the cli_docs tool handler for the MCP server.
+ */
+import type { TopicDoc, CliDocsArgs } from "./types.js";
+/**
+ * All available documentation topics
+ */
+export declare const topics: Record<string, TopicDoc>;
+/**
+ * Get list of all available topic names
+ */
+export declare function getTopicNames(): string[];
+/**
+ * Get topic descriptions for tool documentation
+ */
+export declare function getTopicDescriptions(): string;
+/**
+ * Handler for the cli_docs tool
+ */
+export declare function handleCliDocs(args: CliDocsArgs): string;
+/**
+ * Tool definition for MCP server
+ */
+export declare const cliDocsToolDefinition: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            topic: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+            detail_level: {
+                type: string;
+                enum: string[];
+                default: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+};

package/dist/cli_docs/index.js

@@ -0,0 +1,86 @@
+/**
+ * Xano CLI Documentation Index
+ *
+ * This module exports all documentation topics and provides
+ * the cli_docs tool handler for the MCP server.
+ */
+import { formatDocumentation } from "./format.js";
+// Import all topic documentation
+import { startDoc } from "./topics/start.js";
+import { profileDoc } from "./topics/profile.js";
+import { workspaceDoc } from "./topics/workspace.js";
+import { functionDoc } from "./topics/function.js";
+import { runDoc } from "./topics/run.js";
+import { staticHostDoc } from "./topics/static_host.js";
+import { integrationDoc } from "./topics/integration.js";
+/**
+ * All available documentation topics
+ */
+export const topics = {
+    start: startDoc,
+    profile: profileDoc,
+    workspace: workspaceDoc,
+    function: functionDoc,
+    run: runDoc,
+    static_host: staticHostDoc,
+    integration: integrationDoc,
+};
+/**
+ * Get list of all available topic names
+ */
+export function getTopicNames() {
+    return Object.keys(topics);
+}
+/**
+ * Get topic descriptions for tool documentation
+ */
+export function getTopicDescriptions() {
+    return Object.entries(topics)
+        .map(([key, doc]) => `- ${key}: ${doc.title}`)
+        .join("\n");
+}
+/**
+ * Handler for the cli_docs tool
+ */
+export function handleCliDocs(args) {
+    const { topic, detail_level = "detailed" } = args;
+    // Validate topic
+    if (!topics[topic]) {
+        const available = getTopicNames().join(", ");
+        return `Error: Unknown topic "${topic}".\n\nAvailable topics: ${available}`;
+    }
+    const doc = topics[topic];
+    return formatDocumentation(doc, detail_level);
+}
+/**
+ * Tool definition for MCP server
+ */
+export const cliDocsToolDefinition = {
+    name: "cli_docs",
+    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
+${getTopicDescriptions()}
+
+## Usage
+- Start with "start" topic for installation and setup
+- Use "integration" to understand when to use CLI vs Meta API
+- Use specific topics (profile, workspace, function, run) for command reference`,
+    inputSchema: {
+        type: "object",
+        properties: {
+            topic: {
+                type: "string",
+                enum: getTopicNames(),
+                description: "Documentation topic to retrieve",
+            },
+            detail_level: {
+                type: "string",
+                enum: ["overview", "detailed", "examples"],
+                default: "detailed",
+                description: "Level of detail: overview (brief), detailed (full docs), examples (with examples)",
+            },
+        },
+        required: ["topic"],
+    },
+};

package/dist/cli_docs/topics/function.d.ts

@@ -0,0 +1,2 @@
+import type { TopicDoc } from "../types.js";
+export declare const functionDoc: TopicDoc;

package/dist/cli_docs/topics/function.js

@@ -0,0 +1,114 @@
+export const functionDoc = {
+    topic: "function",
+    title: "Xano CLI - Function Management",
+    description: `Function commands let you list, view, create, and edit individual Xano functions. This is useful for quick edits or when you don't need to sync the entire workspace.`,
+    ai_hints: `**When to use function commands vs workspace commands:**
+- Use \`function:*\` for quick single-function edits
+- Use \`workspace:pull/push\` for bulk operations or version control
+
+**Output formats:**
+- \`summary\` - Human-readable table
+- \`json\` - Full metadata (good for scripting)
+- \`xs\` - Raw XanoScript code only
+
+**Editor integration:**
+- Commands use \`$EDITOR\` environment variable
+- Set to your preferred editor: \`export EDITOR=vim\`
+- Use \`--edit\` flag to open in editor before create/update`,
+    related_topics: ["workspace", "run"],
+    commands: [
+        {
+            name: "function:list",
+            description: "List all functions in the workspace",
+            usage: "xano function:list [options]",
+            flags: [
+                { name: "workspace", short: "w", type: "string", required: false, description: "Workspace ID" },
+                { name: "output", short: "o", type: "string", required: false, default: "summary", description: "Output format: summary, json" },
+                { name: "page", type: "number", required: false, default: "1", description: "Page number" },
+                { name: "per_page", type: "number", required: false, default: "50", description: "Items per page" },
+                { name: "search", type: "string", required: false, description: "Search by name" },
+                { name: "sort", type: "string", required: false, description: "Sort field" },
+                { name: "order", type: "string", required: false, description: "Sort order: asc, desc" },
+                { name: "include_draft", type: "boolean", required: false, description: "Include draft versions" }
+            ],
+            examples: [
+                "xano function:list",
+                "xano function:list --search auth",
+                "xano function:list -o json --include_draft"
+            ]
+        },
+        {
+            name: "function:get",
+            description: "Get a specific function by ID",
+            usage: "xano function:get [function_id] [options]",
+            args: [
+                { name: "function_id", required: false, description: "Function ID (interactive selection if omitted)" }
+            ],
+            flags: [
+                { name: "workspace", short: "w", type: "string", required: false, description: "Workspace ID" },
+                { name: "output", short: "o", type: "string", required: false, default: "summary", description: "Output format: summary, json, xs" },
+                { name: "include_draft", type: "boolean", required: false, description: "Get draft version if available" },
+                { name: "include_xanoscript", type: "boolean", required: false, description: "Include XanoScript in JSON output" }
+            ],
+            examples: [
+                "xano function:get 145",
+                "xano function:get 145 -o xs > my_function.xs",
+                "xano function:get 145 -o json --include_xanoscript"
+            ]
+        },
+        {
+            name: "function:create",
+            description: "Create a new function from XanoScript",
+            usage: "xano function:create [options]",
+            flags: [
+                { name: "workspace", short: "w", type: "string", required: false, description: "Workspace ID" },
+                { name: "file", short: "f", type: "string", required: false, description: "Path to .xs file" },
+                { name: "stdin", type: "boolean", required: false, description: "Read from stdin" },
+                { name: "edit", type: "boolean", required: false, description: "Open in $EDITOR before creating" }
+            ],
+            examples: [
+                "xano function:create -f ./my_function.xs",
+                "cat function.xs | xano function:create --stdin",
+                "xano function:create --edit"
+            ]
+        },
+        {
+            name: "function:edit",
+            description: "Edit an existing function",
+            usage: "xano function:edit [function_id] [options]",
+            args: [
+                { name: "function_id", required: false, description: "Function ID (interactive selection if omitted)" }
+            ],
+            flags: [
+                { name: "workspace", short: "w", type: "string", required: false, description: "Workspace ID" },
+                { name: "file", short: "f", type: "string", required: false, description: "Path to .xs file with updated code" }
+            ],
+            examples: [
+                "xano function:edit 145",
+                "xano function:edit 145 -f ./updated_function.xs"
+            ]
+        }
+    ],
+    workflows: [
+        {
+            name: "Quick Function Edit",
+            description: "Quickly edit a function without full workspace sync",
+            steps: [
+                "Get function code: `xano function:get 145 -o xs > func.xs`",
+                "Edit the file locally",
+                "Upload changes: `xano function:edit 145 -f func.xs`"
+            ],
+            example: `xano function:get 145 -o xs > auth_check.xs
+vim auth_check.xs
+xano function:edit 145 -f auth_check.xs`
+        },
+        {
+            name: "Create from Template",
+            description: "Create a new function from a template file",
+            steps: [
+                "Write your XanoScript function in a .xs file",
+                "Create in Xano: `xano function:create -f template.xs`"
+            ]
+        }
+    ]
+};

package/dist/cli_docs/topics/integration.d.ts

@@ -0,0 +1,2 @@
+import type { TopicDoc } from "../types.js";
+export declare const integrationDoc: TopicDoc;

package/dist/cli_docs/topics/integration.js

@@ -0,0 +1,157 @@
+export const integrationDoc = {
+    topic: "integration",
+    title: "Xano CLI + Meta API Integration Guide",
+    description: `This guide explains when to use the CLI vs the Meta API, and how they work together for different workflows.
+
+> **Note:** The CLI is optional but recommended for local development. Not all users will have it installed. Everything the CLI does can also be accomplished via the Meta API and Run API directly.
+
+## CLI Installation (Optional)
+
+\`\`\`bash
+npm install -g @xano/cli
+\`\`\`
+
+- npm: https://www.npmjs.com/package/@xano/cli
+- GitHub: https://github.com/xano-inc/cli
+
+## CLI vs Meta API
+
+| Task | Use CLI | Use Meta API |
+|------|---------|--------------|
+| Local development | Yes | - |
+| Code sync (pull/push) | Yes | - |
+| Quick function edits | Yes | - |
+| Execute XanoScript | Yes | Yes (Run API) |
+| CI/CD automation | Both | Both |
+| Programmatic management | - | Yes |
+| Create tables/schemas | - | Yes |
+| Manage API groups | - | Yes |
+| Build integrations | - | Yes |
+
+## Authentication
+
+Both use the same access token from your Xano dashboard:
+
+**CLI:** Stored in \`~/.xano/credentials.yaml\`
+\`\`\`bash
+xano profile:wizard  # Interactive setup
+\`\`\`
+
+**Meta API:** Bearer token in Authorization header
+\`\`\`
+Authorization: Bearer <your-token>
+\`\`\`
+
+## API URLs
+
+| API | Base URL | Purpose |
+|-----|----------|---------|
+| Meta API | \`https://<instance>.xano.io/api:meta\` | Manage resources |
+| Run API | \`https://app.dev.xano.com/api:run\` | Execute code |
+
+The CLI uses both APIs internally.`,
+    ai_hints: `**Important:** The CLI is optional. Before suggesting CLI commands, verify the user has it installed or offer to help them install it. All CLI functionality has Meta API equivalents.
+
+**Decision tree for AI:**
+
+1. **User wants to edit code locally?**
+   - With CLI: \`workspace:pull/push\`
+   - Without CLI: Use Meta API \`/workspace/{id}/multidoc\` endpoints
+2. **User wants to execute XanoScript?**
+   - With CLI: \`run:exec\`
+   - Without CLI: Use Run API directly
+3. **User wants to create/modify tables?** → Meta API \`/table\` endpoints
+4. **User wants to create/modify APIs?** → Meta API \`/api\` endpoints
+5. **User wants to manage functions?**
+   - With CLI: \`function:*\` commands for code
+   - Without CLI: Meta API \`/function\` endpoints
+6. **User wants automation in code?** → Meta API (HTTP calls)
+7. **User wants shell scripting?** → CLI commands (if installed)
+
+**If CLI not installed:**
+- Recommend installation: \`npm install -g @xano/cli\`
+- Or use Meta API endpoints directly for equivalent functionality
+- The multidoc endpoint (\`/api:meta/beta/workspace/{id}/multidoc\`) provides pull/push functionality
+
+**Token reuse (if CLI is installed):**
+The same access token works for both:
+\`\`\`bash
+# Get token from CLI profile
+TOKEN=$(xano profile:token)
+
+# Use with Meta API
+curl -H "Authorization: Bearer $TOKEN" https://instance.xano.io/api:meta/workspace
+\`\`\``,
+    related_topics: ["start", "profile", "workspace"],
+    workflows: [
+        {
+            name: "Local Development with Version Control",
+            description: "Full workflow using CLI for code and git for versioning",
+            steps: [
+                "Setup: `xano profile:wizard`",
+                "Pull code: `xano workspace:pull ./xano`",
+                "Init git: `cd xano && git init && git add . && git commit -m 'Initial'`",
+                "Create feature branch: `git checkout -b feature/new-api`",
+                "Edit .xs files in your IDE",
+                "Validate with MCP: Use `validate_xanoscript` tool",
+                "Push to Xano: `xano workspace:push ./xano`",
+                "Test in Xano dashboard",
+                "Commit changes: `git add . && git commit -m 'Add new API'`"
+            ]
+        },
+        {
+            name: "CI/CD Pipeline",
+            description: "Automated deployment using CLI in CI/CD",
+            steps: [
+                "Store XANO_TOKEN as CI secret",
+                "Create profile in CI: `xano profile:create ci -i $INSTANCE -t $XANO_TOKEN`",
+                "Pull from git repo (your versioned .xs files)",
+                "Push to Xano: `xano workspace:push ./xano -p ci`"
+            ],
+            example: `# GitHub Actions example
+- name: Deploy to Xano
+  env:
+    XANO_TOKEN: \${{ secrets.XANO_TOKEN }}
+  run: |
+    npm install -g @xano/cli
+    xano profile:create deploy -i https://x8ki.xano.io -t $XANO_TOKEN -w 1
+    xano workspace:push ./xano -p deploy`
+        },
+        {
+            name: "Create Resources via Meta API + Edit via CLI",
+            description: "Use Meta API to scaffold, CLI to implement",
+            steps: [
+                "Use Meta API to create new function: `POST /workspace/{id}/function`",
+                "Pull workspace: `xano workspace:pull ./xano`",
+                "Find the new function .xs file",
+                "Implement the function logic",
+                "Push changes: `xano workspace:push ./xano`"
+            ]
+        },
+        {
+            name: "Export Token for API Calls",
+            description: "Use CLI-stored credentials with Meta API",
+            steps: [
+                "Get token: `TOKEN=$(xano profile:token)`",
+                "Use in curl: `curl -H \"Authorization: Bearer $TOKEN\" <api-url>`",
+                "Or in code: read token and make HTTP requests"
+            ],
+            example: `# Bash
+TOKEN=$(xano profile:token)
+curl -H "Authorization: Bearer $TOKEN" \\
+  https://x8ki.xano.io/api:meta/workspace`
+        },
+        {
+            name: "Multi-Environment Workflow",
+            description: "Manage staging and production with profiles",
+            steps: [
+                "Create staging profile: `xano profile:create staging -i <url> -t <token> -b 2`",
+                "Create production profile: `xano profile:create prod -i <url> -t <token> -b 1`",
+                "Develop on staging: `xano workspace:pull ./code -p staging`",
+                "Edit and test",
+                "Push to staging: `xano workspace:push ./code -p staging`",
+                "When ready, push to production: `xano workspace:push ./code -p prod`"
+            ]
+        }
+    ]
+};

package/dist/cli_docs/topics/profile.d.ts

@@ -0,0 +1,2 @@
+import type { TopicDoc } from "../types.js";
+export declare const profileDoc: TopicDoc;