MCP Fantom
Semantic Code Search for Fantom and Axon -- Local GPU or OpenRouter
Teach your AI assistant Fantom and Axon -- with or without a GPU of your own.
MCP Fantom gives an AI assistant a working knowledge of a Fantom, Haxall, and 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, SkySpark Axon functions, and the fantom.org and haxall.io documentation; embeds all of it for semantic search; builds a real call graph; and exposes the lot over the Model Context Protocol, alongside a web dashboard for running and watching the indexing.
New in 1.0: OpenRouter
Embedding no longer needs a GPU under your desk. Each inference role -- code embedding, text embedding, reranking, the code assistant, and the retrieval loop -- is routed independently to local hosts, to OpenRouter, or to both at once. Run it entirely in the cloud from a laptop, entirely on your own hardware in an air-gapped plant, or fan out across both pools pulling from one queue.
It Still Migrates SkySpark
SkySpark 4.0 changed the extension format. Hand-migrating a real-world extension or connector is a slog of using rewrites, Axon-string conversions, and brand-new Xeto library files -- with a compiler that bites back the moment you miss a line. MCP Fantom rewrites the using statements, converts the Axon strings, generates the Xeto files, validates with the Fantom compiler, and takes a Git backup tag on the way in.
If the migration breaks, roll back with one tool call. The whole journey is diffable, reversible, and narrated.
Who It's For
- Extension authors migrating SkySpark 3.x pods to 4.0
- Haxall integrators building connectors, functions, and apps in Fantom
- SkySpark developers who want their Axon functions searchable by meaning rather than by grep
- AI-assisted developers who need accurate Fantom context, not hallucinated syntax
Migration Cockpit
Migrate SkySpark 3 to 4 without the hand-cramps
One tool rewrites your extension. Another commits it. A third rolls it back. Every change is diffable, the compiler verifies, Git keeps the safety net.
fan compile. Rollback available via rollbackMigration until commitMigration is called.
Lazy Indexing
The server answers before the index finishes
Most search servers block the client for 30 to 60 seconds on first boot while they index. MCP Fantom boots in under a second. Tools respond immediately -- FlexSearch warms up first, local pods next, embeddings after. The assistant never waits.
Queries degrade transparently. If embeddings are not ready, semantic tools fall back to keyword search. The assistant gets an answer with a note about fidelity, not a timeout.
Code Intelligence
Semantic understanding, not just text match
semanticCodeSearch and findSimilarCode embed your Fantom code into a vector space. Ask for "functions that normalize units" and get results that share structure, not keywords.
Graphology with Louvain clustering finds the natural communities in your codebase -- which types hang together, which ones do not. getCodeImpact traces how a change propagates. getCallers and getCallees round out the call-graph surface.
Migration Safety
Every migration is one undo away
migrateSkySpark4x creates a Git tag before it writes a single byte. If anything fails -- compiler error, validation mismatch, your intuition -- rollbackMigration restores the repo to the exact state before the run.
commitMigration is deliberate. Nothing is merged into your working history until you accept the output. Until then, the migration lives on a branch, with a backup tag, ready to discard.
using rewrites + Axon conversion + Xeto generation.migrateSkySpark4x was called.skyspark-4x-migration, connector-workflow, and xeto-spec-guide.Guided Workflows
Beyond tools -- readable guides
MCP resources are markdown documents the assistant can read on demand. MCP Fantom ships thirteen: a pod scaffolder, a fanr publishing guide, a Haxall extension walkthrough, a fant unit-testing primer, a SkySpark 4.x migration playbook, a Xeto spec guide, and more.
When a developer asks "how do I start?", the assistant pulls the right resource, summarizes, and proceeds. Every workflow is versioned alongside the server.
- ✓ Step-by-step markdown
- ✓ Discoverable via
resources/list - ✓ Versioned with the server
- ✓ Easy to add more
Provider Routing
Your GPU, OpenRouter, or both at once
Every inference role is routed on its own. Embedding can fan out across local GPUs and OpenRouter pulling from one queue, while reranking runs cloud-only and the retrieval loop stays on-premises. Four policies, five roles, set per role and changed at runtime.
A role pointed at OpenRouter becomes a virtual container: real serving capacity with no GPU and no VRAM behind it, registered as its own logical provider so the scheduler can hand it work like any other host. No local model means no local hardware requirement -- MCP Fantom indexes a codebase from a laptop.
- ✓
aggregate-- local and cloud in one fan-out pool - ✓
backup-- local first, cloud held in reserve - ✓
local-- air-gapped, nothing leaves the network - ✓
cloud-- OpenRouter only, no GPU required
0.99 cosine, at the exact configured dimension, before it may write a single row.
Tech Stack
Architecture
Capabilities
- 41 MCP tools -- across documentation search, semantic code search, call-graph analysis, code history, code generation, and migration automation
- Provider routing per role --
code-embedding,embedding,reranker,code-assistant, andrlmeach take their own policy:local,cloud(OpenRouter only),aggregate(both in one fan-out pool), orbackup(local first, cloud held in reserve) - Lazy indexing -- the server boots in seconds and answers immediately; indexing runs in the background and tools degrade gracefully while it does
- Semantic search -- LanceDB behind an ANN index, with an optional cross-encoder or OpenRouter reranker
- Natural-language Q&A --
askCodebaseruns a retrieval loop over the index and synthesizes a cited answer - A real call graph --
getCallers,getCallees,getCodeImpact, andgetCodeNeighborsanswer structural questions from an embedded graph database, not by grepping - Axon support -- SkySpark Axon functions, from synced
proj/folders or offline library exports, parsed with a purpose-built tree-sitter grammar so chunks land on statement boundaries anddefcompcells surface as the component's interface - History --
whatChangedRecently,getSymbolHistory,explainSymbolChange, anddiffIndexRunsanswer how the code got this way - SkySpark 4.x migration -- automated rewrite of
usingstatements and Axon strings, Xeto file generation (lib.trio,funcs.xeto,lib.xeto), compiler validation, Git backup tag, one-call rollback - 13 workflow resources -- readable markdown guides, from
create-podtoskyspark-4x-migration - Dual transport -- stdio and HTTP, with a Next.js dashboard for index coverage, embedding progress, and provider routing
Cloud Without the Footguns
Dropping a cloud embedder into an index a local GPU built is how retrieval quietly rots -- cosine distance stops being comparable and nothing tells you. MCP Fantom treats that as a hard precondition rather than a warning:
- Vector-compatibility gate -- a cloud provider embeds probe texts alongside a reference provider and must clear a 0.99 minimum cosine, at exactly the configured dimension, before it may write a single row. The query encoder always comes from the pool that built those rows.
- Pinned upstreams -- two OpenRouter hosts serving the same model slug do not guarantee identical vectors, so every embedding route has to name its upstream. Reranking is stateless and needs no pin.
- One shared budget -- OpenRouter rate-limits per key, not per caller, so all cloud concurrency is drawn from a single global permit pool, sized from measured latency by Little's Law. A 429 halves the budget and backs off with jitter; the local GPUs keep working straight through it.
- Write-only keys -- the API key passes through to the sidecar that uses it. It is never written to config, never logged, and never returned by any endpoint.
Tool Surface (Partial)
searchFantomCode, semanticCodeSearch, askCodebase, findSimilarCode, getFantomType, getFantomFunction, searchLocalDocs, searchVersionedApi, listFantomPods, getCallers, getCallees, getCodeImpact, getCodeNeighbors, whatChangedRecently, getSymbolHistory, explainSymbolChange, diffIndexRuns, axonSearch, axonFunction, generateFantomCode, migrateSkySpark4x, commitMigration, rollbackMigration, plus project and instance management.
Requirements
- Node.js 20+
- An embedding provider -- a local model or an OpenRouter key
- Local Fantom and Haxall toolchain for migration compiler validation
- Git repository for migration backups
Interested in this project?
Explore the source code, contribute, or get in touch.