Overview

What the Axon MCP Server does, why it exists, and what you can build with it.

What it is

The Axon MCP Server is a Model Context Protocol server that gives AI assistants expert-level access to an Axon codebase. It indexes Axon source files and HTML documentation, exposes search and code-generation tools over MCP, and can execute queries against a live SkySpark instance.

Axon is SkySpark's domain-specific language for building automation, HVAC control, and energy management. The MCP server turns a folder of Axon code into a structured knowledge base that any MCP-compatible client — Claude Desktop, Cursor, the MCP CLI — can query.

What you can do with it

  • Search across Axon code and docs — FlexSearch-powered full-text search with relevance scoring, operator-level queries, and regex patterns.
  • Generate new Axon code — 33 curated YAML templates for common HVAC, energy, fault, and data workflows. Generated code is validated semantically before being returned.
  • Execute code against a live SkySpark instance — run Haystack queries, evaluate Axon expressions, and commit functions with automatic versioning.
  • Analyse call graphs — find callers and callees, detect circular dependencies, identify the most-called or most-complex functions.
  • Semantic search with vector embeddings — natural-language queries that return code by meaning, not just keyword match.

How it fits together

┌──────────────────┐     MCP       ┌──────────────────────┐      HTTP    ┌────────────┐
│ AI client        │ ─────────────▶│ Axon MCP Server      │ ────────────▶│ SkySpark   │
│ (Claude, Cursor) │               │  • search index      │              │ (Haystack) │
│                  │               │  • code generator    │              └────────────┘
│                  │ ◀─────────────│  • graph analyser    │
└──────────────────┘    results    │  • OAuth 2.1         │
                                    └──────────────────────┘
                                              │
                                              ▼
                                       .axon / .trio files
                                       HTML documentation

Connections run over stdio (for local AI clients that spawn the server as a subprocess) or http (for remote clients behind OAuth). The dashboard at /admin provides a web UI for sessions and user management.

Key features

  • Fast search — ~50 ms full-text across thousands of HTML files; initial indexing takes 30–60 s and is cached.
  • OAuth 2.1 with PKCE — multi-user authentication, scoped tokens (mcp:read, mcp:write, mcp:admin).
  • Function versioning — auto-keeps the last 4 revisions of every function committed via the server.
  • Auto-discovery — configure one SkySpark instance; the server enumerates projects and syncs their functions automatically.
  • Local SQLite persistence — user store, backup manifests, and graph metrics all live in a single file via Prisma.

Project status

The server is in active development and is considered stable for search, execution, and code-generation workflows. License: ISC. Issues and contributions are welcome on GitHub.