MCP Fantom

Fantom Documentation, Semantic Code Search, and SkySpark Migration

v0.1.0 Published View Source Documentation

Teach your AI assistant Fantom -- and hand it the keys to your SkySpark 4.0 migration.

MCP Fantom indexes Fantom documentation from fantom.org, your local .fan pods, and Haxall workflows into a single searchable surface. It runs semantic code search across thousands of types and methods, analyzes call graphs with community detection, and -- uniquely -- automates the SkySpark 3.x to 4.0 migration: rewriting using statements, converting Axon strings, generating Xeto files, validating with the Fantom compiler, and taking 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.

Why It Exists

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 turns that work into an assistant-driven workflow that knows the rules, runs the checks, and can undo itself.

Who It's For

  • Extension authors migrating SkySpark 3.x pods to 4.0
  • Haxall integrators building connectors, functions, and apps in Fantom
  • 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.

Migration: in progress modbus-connector
67%
SkySpark 3.x Source
SkySpark 4.0 Output
1using sys
2using skyspark::ext
3using skyspark::folio
4 
5@Ext const class MyConnector : ConnExt {
6  override Str sort := "connector"
7  override Str moniker := "myCon"
8 
9  Str axonWatch() { "read(point and siteRef == @hq)" }
10  Str axonSub() { "readAll(point)" }
11}
12 
1using sys
2using haxall::ext
3using haxall::folio
4 
5@Ext const class MyConnector : ConnExt {
6  override Str sort := "connector"
7  override Str moniker := "myCon"
8  // Axon moved to funcs.xeto
9  Str axonWatch() { "axon:MyConnector.watch" }
10  Str axonSub() { "axon:MyConnector.sub" }
11}
12 
using rewrites: 12 axon strings: 8 xeto files: 3 generated compiler: PASS git: pre-skyspark-4x-backup tag created
Output verified by 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.

MCP Fantom
ready
HTML docs (cheerio) 100%
4,187 of 4,187 pages indexed
Local .fan pods 78%
1,246 of 1,600 pods parsed
Embeddings (LanceDB) 45%
723 of 1,600 vectors computed
Call graph (graphology) 12%
192 of 1,600 functions linked
boot 0s tools 1s docs 8s full index 47s
Semantic Search LanceDB
"functions that normalize units" cosine search
normalizeUnit(val, target)
Canonicalize a numeric value to a target unit symbol.
0.91
convertUnit(point, u)
Convert a point's value into the specified unit.
0.87
toEngUnit(v, sym)
Return the engineering-unit representation of a raw value.
0.82
Code Communities (Louvain)
unit normalization trio parsing meter reads connector utils

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.

semanticCodeSearch findSimilarCode getCallers getCallees getCodeImpact

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.

Git Timeline mcp-fantom repo
commitMigration merged
ghi789
All Xeto files written; compile PASS confirmed.
migration branch applied
def456
using rewrites + Axon conversion + Xeto generation.
tag: pre-skyspark-4x-backup
abc123
Backup tag created automatically before migration run.
pre-migration state
abc123
Repo state before migrateSkySpark4x was called.
Migration Tools
migrateSkySpark4x
Run the full rewrite.
commitMigration
Accept the output.
rollbackMigration
Restore to backup tag.
resources/list --> 4 resources
create-pod
Scaffold a new Fantom pod end-to-end.
5 steps · markdown
use-fanr
Publish a pod via fanr.
6 steps · markdown
haxall-basics
Build your first Haxall extension.
8 steps · markdown
unit-testing
Set up fant unit tests.
4 steps · markdown

Guided Workflows

Beyond tools -- readable guides

MCP resources are markdown documents the assistant can read on demand. MCP Fantom ships four: a pod scaffolder, a fanr publishing guide, a Haxall extension walkthrough, and a fant unit-testing primer.

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

Interested in this project?

Explore the source code, contribute, or get in touch.

View on GitHub Get in Touch