@xano/developer-mcp 1.0.25 → 1.0.27

package/dist/cli_docs/topics/workspace.js

@@ -0,0 +1,119 @@
+export const workspaceDoc = {
+    topic: "workspace",
+    title: "Xano CLI - Workspace Operations",
+    description: `Workspace commands let you sync XanoScript code between your local filesystem and Xano. This enables version control, local editing, and CI/CD workflows.
+
+## Multidoc Format
+
+Xano uses a "multidoc" format where multiple XanoScript documents are separated by \`---\`:
+
+\`\`\`xanoscript
+# functions/auth.xs
+---
+function: validate_token
+...
+---
+function: refresh_token
+...
+\`\`\`
+
+When you pull, the CLI splits these into individual \`.xs\` files organized by type.`,
+    ai_hints: `**Key concepts:**
+- \`pull\` downloads workspace code and splits into organized .xs files
+- \`push\` combines .xs files and uploads to Xano
+- Files are organized by type: functions/, apis/, tasks/, etc.
+
+**Typical workflow:**
+1. \`xano workspace:pull ./xano-code\` - download
+2. Edit .xs files with your editor/IDE
+3. \`xano workspace:push ./xano-code\` - deploy
+
+**Version control:**
+- The pulled directory structure is git-friendly
+- Commit changes to track history
+- Use branches for different environments
+
+**Branch handling:**
+- Use \`-b\` flag or set branch in profile
+- Pull from one branch, push to another is supported`,
+    related_topics: ["start", "function", "integration"],
+    commands: [
+        {
+            name: "workspace:list",
+            description: "List all workspaces accessible to your account",
+            usage: "xano workspace:list [-p <profile>]",
+            examples: ["xano workspace:list", "xano workspace:list -p production"]
+        },
+        {
+            name: "workspace:pull",
+            description: "Download workspace code to local directory",
+            usage: "xano workspace:pull <directory> [options]",
+            args: [
+                { name: "directory", required: true, description: "Local directory to save files" }
+            ],
+            flags: [
+                { name: "workspace", short: "w", type: "string", required: false, description: "Workspace ID (uses profile default if not set)" },
+                { name: "branch", short: "b", type: "string", required: false, description: "Branch ID to pull from" },
+                { name: "env", type: "boolean", required: false, description: "Include environment variables" },
+                { name: "records", type: "boolean", required: false, description: "Include table records" }
+            ],
+            examples: [
+                "xano workspace:pull ./my-app",
+                "xano workspace:pull ./staging-code -b 2",
+                "xano workspace:pull ./backup --env --records"
+            ]
+        },
+        {
+            name: "workspace:push",
+            description: "Upload local XanoScript files to workspace",
+            usage: "xano workspace:push <directory> [options]",
+            args: [
+                { name: "directory", required: true, description: "Local directory containing .xs files" }
+            ],
+            flags: [
+                { name: "workspace", short: "w", type: "string", required: false, description: "Workspace ID (uses profile default if not set)" },
+                { name: "branch", short: "b", type: "string", required: false, description: "Branch ID to push to" }
+            ],
+            examples: [
+                "xano workspace:push ./my-app",
+                "xano workspace:push ./my-app -b 2"
+            ]
+        }
+    ],
+    workflows: [
+        {
+            name: "Local Development Cycle",
+            description: "Edit Xano code locally with your preferred tools",
+            steps: [
+                "Pull workspace: `xano workspace:pull ./code`",
+                "Edit .xs files in your IDE",
+                "Validate changes: Use xanoscript_docs MCP tool",
+                "Push changes: `xano workspace:push ./code`",
+                "Test in Xano dashboard or via API"
+            ],
+            example: `xano workspace:pull ./my-app
+# Edit files...
+xano workspace:push ./my-app`
+        },
+        {
+            name: "Version Control Setup",
+            description: "Track Xano code changes in git",
+            steps: [
+                "Pull workspace: `xano workspace:pull ./xano`",
+                "Initialize git: `cd xano && git init`",
+                "Add files: `git add . && git commit -m 'Initial import'`",
+                "Make changes and commit regularly",
+                "Push to Xano when ready: `xano workspace:push ./xano`"
+            ]
+        },
+        {
+            name: "Cross-Branch Deployment",
+            description: "Promote code from staging to production",
+            steps: [
+                "Pull from staging: `xano workspace:pull ./deploy -b staging`",
+                "Review changes",
+                "Push to production: `xano workspace:push ./deploy -b production`"
+            ]
+        }
+    ]
+};

package/dist/cli_docs/types.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Type definitions for Xano CLI documentation
+ */
+export interface CommandDoc {
+    name: string;
+    description: string;
+    usage: string;
+    flags?: FlagDoc[];
+    args?: ArgDoc[];
+    examples?: string[];
+}
+export interface FlagDoc {
+    name: string;
+    short?: string;
+    type: string;
+    required?: boolean;
+    default?: string;
+    description: string;
+}
+export interface ArgDoc {
+    name: string;
+    required?: boolean;
+    description: string;
+}
+export interface WorkflowDoc {
+    name: string;
+    description: string;
+    steps: string[];
+    example?: string;
+}
+export interface TopicDoc {
+    topic: string;
+    title: string;
+    description: string;
+    commands?: CommandDoc[];
+    workflows?: WorkflowDoc[];
+    related_topics?: string[];
+    ai_hints?: string;
+}
+export type DetailLevel = "overview" | "detailed" | "examples";
+export interface CliDocsArgs {
+    topic: string;
+    detail_level?: DetailLevel;
+}

package/dist/cli_docs/types.js

@@ -0,0 +1,4 @@
+/**
+ * Type definitions for Xano CLI documentation
+ */
+export {};

package/dist/index.js

@@ -9,6 +9,7 @@ import { xanoscriptParser } from "@xano/xanoscript-language-server/parser/parser
 import { getSchemeFromContent } from "@xano/xanoscript-language-server/utils.js";
 import { metaApiDocsToolDefinition, handleMetaApiDocs } from "./meta_api_docs/index.js";
 import { runApiDocsToolDefinition, handleRunApiDocs } from "./run_api_docs/index.js";
+import { cliDocsToolDefinition, handleCliDocs } from "./cli_docs/index.js";
 import { XANOSCRIPT_DOCS_V2, readXanoscriptDocsV2, getXanoscriptDocsVersion, getTopicDescriptions, } from "./xanoscript.js";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -146,6 +147,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             },
             metaApiDocsToolDefinition,
             runApiDocsToolDefinition,
+            cliDocsToolDefinition,
         ],
     };
 });
@@ -322,6 +324,46 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             };
         }
     }
+    if (request.params.name === "cli_docs") {
+        const args = request.params.arguments;
+        if (!args?.topic) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: "Error: 'topic' parameter is required. Use cli_docs with topic='start' for overview.",
+                    },
+                ],
+                isError: true,
+            };
+        }
+        try {
+            const documentation = handleCliDocs({
+                topic: args.topic,
+                detail_level: args.detail_level,
+            });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: documentation,
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Error retrieving CLI documentation: ${errorMessage}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    }
     return {
         content: [
             {

package/dist/xanoscript_docs/README.md

@@ -4,21 +4,21 @@ XanoScript is the declarative scripting language for [Xano](https://xano.com), a
 
 ## Quick Reference
 
-| Construct | File Location | Purpose |
-|-----------|---------------|---------|
-| `table` | `tables/*.xs` | Database schema definition |
-| `function` | `functions/**/*.xs` | Reusable logic blocks |
-| `query` | `apis/<group>/*.xs` | HTTP API endpoints |
-| `task` | `tasks/*.xs` | Scheduled/cron jobs |
-| `*_trigger` | `triggers/**/*.xs` | Event-driven handlers |
-| `agent` | `agents/**/*.xs` | AI-powered agents |
-| `tool` | `tools/**/*.xs` | Tools for AI agents |
-| `mcp_server` | `mcp_servers/**/*.xs` | MCP server definitions |
-| `addon` | `addons/*.xs` | Subqueries for related data |
-| `middleware` | `middleware/**/*.xs` | Request/response interceptors |
-| `branch` | `branch.xs` | Branch-level configuration |
-| `workspace` | `workspace.xs` | Workspace-level configuration |
-| `realtime_channel` | Configuration | Realtime channel settings |
+| Construct          | File Location         | Purpose                       |
+| ------------------ | --------------------- | ----------------------------- |
+| `table`            | `tables/*.xs`         | Database schema definition    |
+| `function`         | `functions/**/*.xs`   | Reusable logic blocks         |
+| `query`            | `apis/<group>/*.xs`   | HTTP API endpoints            |
+| `task`             | `tasks/*.xs`          | Scheduled/cron jobs           |
+| `*_trigger`        | `triggers/**/*.xs`    | Event-driven handlers         |
+| `agent`            | `agents/**/*.xs`      | AI-powered agents             |
+| `tool`             | `tools/**/*.xs`       | Tools for AI agents           |
+| `mcp_server`       | `mcp_servers/**/*.xs` | MCP server definitions        |
+| `addon`            | `addons/*.xs`         | Subqueries for related data   |
+| `middleware`       | `middleware/**/*.xs`  | Request/response interceptors |
+| `branch`           | `branch.xs`           | Branch-level configuration    |
+| `workspace`        | `workspace.xs`        | Workspace-level configuration |
+| `realtime_channel` | Configuration         | Realtime channel settings     |
 
 **Important:** Each `.xs` file must contain exactly one definition. You cannot define multiple tables, functions, queries, or other constructs in a single file.
 
@@ -47,21 +47,22 @@ project/
 
 Access with `$env.<name>`. Built-in variables:
 
-| Variable | Description |
-|----------|-------------|
-| `$env.$remote_ip` | Client IP address |
-| `$env.$http_headers` | Request headers array |
-| `$env.$request_uri` | Request URI |
-| `$env.$request_method` | HTTP method (GET, POST, etc.) |
-| `$env.$request_querystring` | Query string |
-| `$env.$datasource` | Current datasource |
-| `$env.$branch` | Current branch |
+| Variable                    | Description                   |
+| --------------------------- | ----------------------------- |
+| `$env.$remote_ip`           | Client IP address             |
+| `$env.$http_headers`        | Request headers array         |
+| `$env.$request_uri`         | Request URI                   |
+| `$env.$request_method`      | HTTP method (GET, POST, etc.) |
+| `$env.$request_querystring` | Query string                  |
+| `$env.$datasource`          | Current datasource            |
+| `$env.$branch`              | Current branch                |
 
 Custom environment variables are set in the Xano dashboard and accessed as `$env.MY_VAR`.
 
 ## Core Syntax Patterns
 
 ### Block Structure
+
 ```xs
 <construct> "<name>" {
   input { ... }      // Parameters (optional)
@@ -71,6 +72,7 @@ Custom environment variables are set in the Xano dashboard and accessed as `$env
 ```
 
 ### Variable Access
+
 ```xs
 $input.field        // Input parameters
 $var.field          // Stack variables
@@ -83,14 +85,18 @@ $this               // Current item in loops/maps
 **Note:** `$response` is a reserved word and cannot be used as a variable name.
 
 ### Comments
+
 ```xs
 // Single-line comment
-var $total { value = 0 }  // Inline comment
+var $total {
+  value = 0
+}
 ```
 
 **Note:** XanoScript only supports `//` for comments. Other comment styles like `#` are not supported.
 
 ### Filters (Pipe Syntax)
+
 ```xs
 $value|trim|lower                    // Chain filters
 $input.name|strlen                   // Get length
@@ -115,58 +121,66 @@ This helps AI tools apply the correct documentation based on the file being edit
 Use `xanoscript_docs({ topic: "<topic>" })` to retrieve documentation.
 
 ### Core Language
-| Topic | Description |
-|-------|-------------|
-| `syntax` | Expressions, operators, filters, system variables |
-| `types` | Data types, validation, input blocks |
-| `functions` | Reusable function stacks, async, loops |
-| `schema` | Runtime schema parsing and validation |
+
+| Topic       | Description                                       |
+| ----------- | ------------------------------------------------- |
+| `syntax`    | Expressions, operators, filters, system variables |
+| `types`     | Data types, validation, input blocks              |
+| `functions` | Reusable function stacks, async, loops            |
+| `schema`    | Runtime schema parsing and validation             |
 
 ### Data
-| Topic | Description |
-|-------|-------------|
-| `tables` | Database schema definitions with indexes and relationships |
-| `database` | All db.* operations: query, get, add, edit, patch, delete |
-| `addons` | Reusable subqueries for fetching related data |
-| `streaming` | Streaming data from files, requests, and responses |
+
+| Topic       | Description                                                |
+| ----------- | ---------------------------------------------------------- |
+| `tables`    | Database schema definitions with indexes and relationships |
+| `database`  | All db.\* operations: query, get, add, edit, patch, delete |
+| `addons`    | Reusable subqueries for fetching related data              |
+| `streaming` | Streaming data from files, requests, and responses         |
 
 ### APIs & Endpoints
-| Topic | Description |
-|-------|-------------|
-| `apis` | HTTP endpoint definitions with authentication and CRUD patterns |
-| `tasks` | Scheduled and cron jobs |
-| `triggers` | Event-driven handlers (table, realtime, workspace, agent, MCP) |
-| `realtime` | Real-time channels and events for push updates |
+
+| Topic      | Description                                                     |
+| ---------- | --------------------------------------------------------------- |
+| `apis`     | HTTP endpoint definitions with authentication and CRUD patterns |
+| `tasks`    | Scheduled and cron jobs                                         |
+| `triggers` | Event-driven handlers (table, realtime, workspace, agent, MCP)  |
+| `realtime` | Real-time channels and events for push updates                  |
 
 ### AI & Agents
-| Topic | Description |
-|-------|-------------|
-| `agents` | AI agent configuration with LLM providers and tools |
-| `tools` | AI tools for agents and MCP servers |
-| `mcp-servers` | MCP server definitions exposing tools |
+
+| Topic         | Description                                         |
+| ------------- | --------------------------------------------------- |
+| `agents`      | AI agent configuration with LLM providers and tools |
+| `tools`       | AI tools for agents and MCP servers                 |
+| `mcp-servers` | MCP server definitions exposing tools               |
 
 ### Integrations
-| Topic | Description |
-|-------|-------------|
+
+| Topic          | Description                                       |
+| -------------- | ------------------------------------------------- |
 | `integrations` | Cloud storage, Redis, security, and external APIs |
 
 ### Configuration
-| Topic | Description |
-|-------|-------------|
-| `workspace` | Workspace-level settings: environment variables, preferences, realtime |
-| `branch` | Branch-level settings: middleware, history retention, visual styling |
+
+| Topic        | Description                                                            |
+| ------------ | ---------------------------------------------------------------------- |
+| `workspace`  | Workspace-level settings: environment variables, preferences, realtime |
+| `branch`     | Branch-level settings: middleware, history retention, visual styling   |
 | `middleware` | Request/response interceptors for functions, queries, tasks, and tools |
 
 ### Development
-| Topic | Description |
-|-------|-------------|
-| `testing` | Unit tests, mocks, and assertions |
-| `debugging` | Logging, inspecting, and debugging XanoScript execution |
-| `frontend` | Static frontend development and deployment |
-| `run` | Run job and service configurations for the Xano Job Runner |
+
+| Topic       | Description                                                |
+| ----------- | ---------------------------------------------------------- |
+| `testing`   | Unit tests, mocks, and assertions                          |
+| `debugging` | Logging, inspecting, and debugging XanoScript execution    |
+| `frontend`  | Static frontend development and deployment                 |
+| `run`       | Run job and service configurations for the Xano Job Runner |
 
 ### Best Practices
-| Topic | Description |
-|-------|-------------|
-| `performance` | Performance optimization best practices |
-| `security` | Security best practices for authentication and authorization |
+
+| Topic         | Description                                                  |
+| ------------- | ------------------------------------------------------------ |
+| `performance` | Performance optimization best practices                      |
+| `security`    | Security best practices for authentication and authorization |