claude mcp add xano -- npx -y @xano/developer-mcp

npm install -g @xano/developer-mcp

claude mcp add xano-developer -- xano-developer-mcp

{
  "mcpServers": {
    "xano-developer": {
      "command": "npx",
      "args": ["-y", "@xano/developer-mcp"]
    }
  }
}

npx skills add xano-inc/xano-developer-mcp -s xano-init -a claude-code -g

npx skills add xano-inc/xano-developer-mcp -s xano-init \
  -a claude-code -a codex -a cursor -a opencode -g

npx @xano/developer-mcp --version

node dist/index.js --version

# Clone the repository
git clone https://github.com/xano-inc/xano-developer-mcp.git
cd xano-developer-mcp

# Install dependencies
npm install

# Build the project
npm run build

# Production
npm start

# Development (build + run)
npm run dev

claude mcp add xano-developer node /path/to/xano-developer-mcp/dist/index.js

{
  "mcpServers": {
    "xano-developer": {
      "command": "node",
      "args": ["/path/to/xano-developer-mcp/dist/index.js"]
    }
  }
}

npm install @xano/developer-mcp

import {
  validateXanoscript,
  xanoscriptDocs,
  metaApiDocs,
  cliDocs,
  mcpVersion
} from '@xano/developer-mcp';

import { validateXanoscript } from '@xano/developer-mcp';

// Validate code directly
const result = validateXanoscript({ code: 'var:result = 1 + 2' });

if (result.valid) {
  console.log('Code is valid!');
} else {
  console.log('Validation errors:');
  result.errors.forEach(error => {
    console.log(`  Line ${error.range.start.line + 1}: ${error.message}`);
  });
}

// Validate a file
const fileResult = validateXanoscript({ file_path: './function/utils.xs' });

// Batch validate a directory
const dirResult = validateXanoscript({ directory: './api', pattern: '**/*.xs' });
console.log(`${dirResult.valid_files}/${dirResult.total_files} files valid`);

import { xanoscriptDocs } from '@xano/developer-mcp';

// Get the compact topic index (the no-arg default; ~4KB / ~1K tokens)
const index = xanoscriptDocs();
console.log(index.documentation);

// Get the full prose overview (the previous no-arg default)
const overview = xanoscriptDocs({ topic: 'readme' });

// Get specific topic
const syntaxDocs = xanoscriptDocs({ topic: 'syntax' });

// Get context-aware docs for a file path
const apiDocs = xanoscriptDocs({ file_path: 'api/users/create_post.xs' });

// Get compact quick reference
const quickRef = xanoscriptDocs({ topic: 'database', mode: 'quick_reference' });

import { metaApiDocs } from '@xano/developer-mcp';

// Get overview
const overview = metaApiDocs({ topic: 'start' });

// Get detailed documentation with examples
const workspaceDocs = metaApiDocs({
  topic: 'workspace',
  detail_level: 'examples',
  include_schemas: true
});

console.log(workspaceDocs.documentation);

import { cliDocs } from '@xano/developer-mcp';

const cliSetup = cliDocs({ topic: 'start' });
console.log(cliSetup.documentation);

import { mcpVersion } from '@xano/developer-mcp';

const { version } = mcpVersion();
console.log(`Using version ${version}`);

import type {
  ValidateXanoscriptArgs,
  ValidationResult,
  ParserDiagnostic,
  XanoscriptDocsArgs,
  MetaApiDocsArgs,
  CliDocsArgs,
  ToolResult
} from '@xano/developer-mcp';

// Main library entry (recommended)
import { validateXanoscript } from '@xano/developer-mcp';

// Tools module directly
import { validateXanoscript } from '@xano/developer-mcp/tools';

// Server module (for extending the MCP server)
import '@xano/developer-mcp/server';

// Validate code directly
xano_validate_xanoscript({ code: "var:result = 1 + 2" })

// Validate a single file
xano_validate_xanoscript({ file_path: "function/utils/format.xs" })

// Validate multiple files
xano_validate_xanoscript({ file_paths: ["api/users/get.xs", "api/users/create.xs"] })

// Validate all .xs files in a directory
xano_validate_xanoscript({ directory: "api/users" })

// Validate with a specific pattern
xano_validate_xanoscript({ directory: "src", pattern: "api/**/*.xs" })

// Get the compact topic index (no-arg default)
xano_xanoscript_docs()

// Get the full prose overview (previous no-arg default)
xano_xanoscript_docs({ topic: "readme" })

// Get survival kit for small context models (~1.2K tokens)
xano_xanoscript_docs({ tier: "survival" })

// Get working reference for medium context models (~4.4K tokens)
xano_xanoscript_docs({ tier: "working" })

// Get essentials (recommended first stop)
xano_xanoscript_docs({ topic: "essentials" })

// Get specific topic
xano_xanoscript_docs({ topic: "functions" })

// Discover available topics with sizes
xano_xanoscript_docs({ mode: "index" })

// Budget-aware: load docs up to token limit
xano_xanoscript_docs({ file_path: "api/users/create_post.xs", max_tokens: 2000 })

// Context-aware: get all docs relevant to file being edited
xano_xanoscript_docs({ file_path: "api/users/create_post.xs" })

// Context-aware with exclusions (skip already-loaded topics)
xano_xanoscript_docs({ file_path: "api/users/create_post.xs", exclude_topics: ["syntax", "essentials"] })

// Compact quick reference (uses less context)
xano_xanoscript_docs({ topic: "database", mode: "quick_reference" })

xano_version()

// Get overview of Meta API
xano_meta_api_docs({ topic: "start" })

// Get detailed table documentation
xano_meta_api_docs({ topic: "table", detail_level: "detailed" })

// Get examples without schemas (smaller context)
xano_meta_api_docs({ topic: "api", detail_level: "examples", include_schemas: false })

// Step-by-step workflow guides
xano_meta_api_docs({ topic: "workflows" })

// Get CLI setup guide
xano_cli_docs({ topic: "start" })

// Learn when to use CLI vs Meta API
xano_cli_docs({ topic: "integration" })

// Get workspace sync commands
xano_cli_docs({ topic: "workspace", detail_level: "detailed" })

// Profile management with examples
xano_cli_docs({ topic: "profile", detail_level: "examples" })

xano-developer-mcp/
├── src/
│   ├── index.ts                        # MCP server entry point
│   ├── lib.ts                          # Library entry point (for npm imports)
│   ├── xanoscript.ts                   # XanoScript documentation logic
│   ├── xanoscript.test.ts              # Tests for xanoscript module
│   ├── xanoscript-language-server.d.ts # TypeScript declarations
│   ├── tools/                          # Standalone tool modules
│   │   ├── index.ts                    # Unified tool exports & handler
│   │   ├── index.test.ts               # Tests for tool handler
│   │   ├── types.ts                    # Common types (ToolResult)
│   │   ├── validate_xanoscript.ts      # XanoScript validation tool
│   │   ├── xanoscript_docs.ts          # XanoScript docs tool
│   │   ├── xanoscript_docs.test.ts     # Tests for xanoscript docs tool
│   │   ├── mcp_version.ts              # Version tool
│   │   ├── meta_api_docs.ts            # Meta API docs tool wrapper
│   │   └── cli_docs.ts                 # CLI docs tool wrapper
│   ├── meta_api_docs/                  # Meta API documentation
│   │   ├── index.ts                    # API docs handler
│   │   ├── index.test.ts               # Tests for index
│   │   ├── types.ts                    # Type definitions
│   │   ├── types.test.ts               # Tests for types
│   │   ├── format.ts                   # Documentation formatter
│   │   ├── format.test.ts              # Tests for formatter
│   │   └── topics/                     # Individual topic modules
│   ├── cli_docs/                       # Xano CLI documentation
│   │   ├── index.ts                    # CLI docs handler
│   │   ├── types.ts                    # Type definitions
│   │   ├── format.ts                   # Documentation formatter
│   │   └── topics/                     # Individual topic modules
│   └── xanoscript_docs/                # XanoScript language documentation
│       ├── docs_index.json             # Machine-readable topic registry
│       ├── version.json
│       ├── README.md
│       ├── essentials.md
│       ├── syntax.md
│       ├── syntax/                     # Syntax sub-topics
│       │   ├── string-filters.md
│       │   ├── array-filters.md
│       │   └── functions.md
│       └── ...
├── dist/                               # Compiled JavaScript output
├── vitest.config.ts                    # Test configuration
├── package.json
└── tsconfig.json

AI Client
    │
    ▼
MCP Protocol (JSON-RPC over stdio)
    │
    ▼
Xano Developer MCP Server
    │
    ├─► xano_validate_xanoscript → Parses code with XanoScript language server
    │
    ├─► xano_xanoscript_docs → Context-aware docs from /xanoscript_docs/*.md
    │
    ├─► xano_meta_api_docs → Meta API documentation with detail levels
    │
    ├─► xano_cli_docs → CLI documentation for local development workflows
    │
    ├─► xano_version → Returns server version from package.json
    │
    └─► MCP Resources → Direct access to XanoScript documentation

npm run build

# Run all tests
npm test

# Run tests in watch mode (re-runs on file changes)
npm run test:watch

# Run tests with coverage report
npm run test:coverage

src/
├── xanoscript.ts
├── xanoscript.test.ts          # Tests for xanoscript.ts
├── tools/
│   ├── index.ts
│   ├── index.test.ts           # Tests for tool handler
│   ├── xanoscript_docs.ts
│   ├── xanoscript_docs.test.ts # Tests for xanoscript docs tool
│   └── ...
├── meta_api_docs/
│   ├── index.ts
│   ├── index.test.ts           # Tests for index.ts
│   ├── format.ts
│   ├── format.test.ts          # Tests for format.ts
│   └── ...

import { describe, it, expect } from "vitest";
import { myFunction } from "./myModule.js";

describe("myFunction", () => {
  it("should return expected result", () => {
    expect(myFunction("input")).toBe("expected");
  });
});

// 1.x
const result = handleTool("xanoscript_docs", { topic: "syntax" });

// 2.0
const result = await handleTool("xano_xanoscript_docs", { topic: "syntax" });

// 1.x
import { validateXanoscriptToolDefinition } from "@xano/developer-mcp";

// 2.0
import { toolSpecs } from "@xano/developer-mcp";
const validateXanoscriptToolDefinition =
  toolSpecs.xano_validate_xanoscript.definition;