FantomMcpServer

A Model Context Protocol server that gives AI assistants a working knowledge of a Fantom / Haxall / SkySpark codebase — not just its documentation, but the actual code: what calls what, what changed last week, and which function does the thing you are describing in plain English.

It indexes Fantom source and Axon functions, embeds them for semantic search, builds a call graph, and exposes all of it over MCP alongside a web dashboard for running and watching the indexing.

Status: 1.0.0 — first public release.

What it does

Semantic code search. Ask "where do we roll up point history by day and normalise by revenue" and get the functions that implement it, not the ones that happen to contain those words. Code is chunked at syntactic boundaries, embedded, and searched by vector similarity with an optional cross-encoder rerank.

Natural-language Q&A over the codebase. askCodebase runs a retrieval loop over the index and synthesises a cited answer.

A real call graph. getCallers, getCallees, getCodeImpact and getCodeNeighbors answer structural questions — stored in an embedded graph database, not recomputed by grepping.

Axon support. SkySpark Axon functions (both synced proj/ folders and offline library exports) are parsed with a tree-sitter grammar, so chunks land on statement boundaries, defcomp cells are surfaced as the component's interface, and comments are preserved as search signal.

History. whatChangedRecently, getSymbolHistory, explainSymbolChange and diffIndexRuns answer questions about how the code got this way.

Documentation. Fantom (fantom.org) and Haxall (haxall.io) docs are crawled and indexed, plus any local pod docs.

SkySpark 3.x → 4.0 migration. migrateSkySpark4x automates the transformation and tags a backup first; commitMigration / rollbackMigration finish or undo it.

41 MCP tools in total.

Related MCP server: CodeGraph

Requirements

• Node.js 20+

• An embedding provider — either a local model or an OpenRouter key (see Embedding providers)

• Optional: a running SkySpark instance for live Axon evaluation; everything else works offline

Install

git clone https://github.com/Project-SandStar/FantomMcpServer.git
cd FantomMcpServer
npm install          # also runs prisma generate
npm run build

Run

npm start            # stdio transport (Claude Desktop / CLI)
npm run start:http   # HTTP transport + dashboard on :3847
npm run dev          # stdio, tsx watch

Connect an MCP client

{
  "mcpServers": {
    "fantom": {
      "command": "node",
      "args": ["/absolute/path/to/FantomMcpServer/build/index.js"]
    }
  }
}

For HTTP mode, point the client at http://localhost:3847/mcp.

Dashboard

npm run dashboard:install
npm run dashboard:build
npm run start:http

Then open http://localhost:3847/dashboard/. It shows index coverage, embedding progress, the vector and graph stores, provider routing, and per-project controls. The admin API is behind Basic Auth — change the default credentials before exposing it.

Configuration

Runtime configuration lives in config/fantomMcpServer-config.json, created from the example on first start. Nothing in config/ is version-controlled except the examples.

cp config/fantomMcpServer-config.example.json config/fantomMcpServer-config.json
cp .env.example .env

Embedding providers

Each role (code-embedding, embedding, reranker, code-assistant, rlm) is routed independently by policy:

Cloud providers must pass a vector-compatibility check before they may write into a table, so a corpus is never half-built from vectors that do not match the query encoder. The query encoder always comes from the same pool that built the rows.

Data it stores

All generated locally under .cache/, all regenerable, none of it version-controlled:

Delete .cache/ to start clean; the server rebuilds on the next index run.

Development

npm test             # Jest suite
npm run build        # tsc + copy workflows
npm run clean        # drop build/ and .cache/
npm run test:search  # search smoke test

Notes for contributors:

• Source files are kept under ~25k tokens so they stay readable in one pass.

• src/admin/routes.ts is large — read it with an offset.

• The Axon tree-sitter grammar source is in tree-sitter-axon/; the compiled grammar ships in assets/grammars/.

Layout

src/
  index.ts          MCP server (stdio + HTTP)
  admin/            admin REST API
  axon/             Axon parsing, indexing, search
  embedding/        providers, routing, vector stores
  graph/            LadybugDB code graph
  fantom-parser/    Fantom tokenizer and parser
  migration/        SkySpark 3.x → 4.0
  parser/           documentation crawlers
  search/           FlexSearch index
dashboard/          Next.js admin UI
assets/grammars/    compiled tree-sitter grammars
workflows/          markdown guides served as MCP resources

Security

• config/ and .env are git-ignored; only *.example.json and .env.example are tracked.

• The admin API ships with admin/admin. Change it before binding to anything but localhost.

• Indexed source and embeddings stay in .cache/ on your machine. Nothing is uploaded unless you configure a cloud provider, in which case code chunks are sent to that provider for embedding.

License

Project Sandstar Source-Available License (PSSL) v1.1.

Links

• Model Context Protocol

• Fantom · Haxall · SkySpark