sphereserver-mcp

Expert MCP server for SphereServer (Ultima Online emulator) and the .scp scripting language — version-aware, RAG-backed, and source-grounded.

sphereserver-mcp is a Model Context Protocol server that turns any MCP-capable client (GitHub Copilot, Claude Code, OpenCode, Cursor, Continue…) into a domain expert on SphereServer SCP scripting — across Sphere 0.55+, 56d and Sphere X.

It ingests, indexes and exposes:

• 🧠 the Source-X and Source-Archive C++ codebases (function signatures, intrinsics, defaults),
• 📜 the Scripts-X official script library (canonical SCP examples),
• 📖 the Sphere Community Wiki (cleaned, deduped, version-tagged),
• 📝 changelogs + git history to build an evolutionary timeline of every keyword,
• 🎨 the vscode-scp-extension grammar (tokens, scopes, keywords),
• 💬 issues & discussions for tribal knowledge.

…and answers SCP questions with citations, version tags, and a modern-vs-legacy verdict instead of hallucinations.

✨ Features

| Capability | Description | | ------------------------------- | --------------------------------------------------------------------------------------------------- | | SCP generation | Produce idiomatic SCP for a target version (0.55i, 56d, 0.56b, X 0.99…). | | Explanation | Inline explanations of any block, with links to wiki / Source-X. | | Autocomplete-grade lookup | Resolve any DEFNAME, TYPEDEF, EVENT, TRIGGER, FUNCTION, TAG, VAR, UID, intrinsic. | | Error detection | Static analysis: missing [ENDIF], dangling TAG., deprecated SERV. calls, broken DIALOG ids. | | Legacy → Modern migration | Rewrites 0.55-era scripts into Sphere X idioms with a diff. | | Deprecated-syntax detection | Flags keywords removed/renamed, with the commit that removed them. | | Cross-version compatibility | "Will this run on 56d AND X?" — yes/no with the differing lines. | | Doc generation | Generates per-ITEMDEF/CHARDEF/FUNCTION documentation blocks. | | Snippet library | Curated, reusable DIALOG, MENU, NPC AI, timer, region templates. | | Version-aware search | "Show me TIMERF usage as it existed in 56d only". | | Timeline / blame | "When did TAG0. appear? When was SRC. introduced?" | | Knowledge graph | Symbols ⇄ triggers ⇄ events ⇄ examples ⇄ wiki pages ⇄ commits. |

🚀 Quick start

1. Install

There are two equally supported install styles. Pick npx if you want zero-effort auto-updates; pick the global install if you prefer fully offline / pinned operation.

Option A — zero-install, always latest (recommended)

Let your MCP client launch the server through npx. The @latest tag forces a registry check on each spawn, so you always get the newest release without manual updates:

npx -y sphereserver-mcp@latest --help

The first spawn after a new release downloads it (a few seconds); cached spawns reuse it instantly. No global install required.

Option B — global install (pinned)

Uses pnpm (≥ 10). It's strict, fast, and the repository enforces it via preinstall (only-allow pnpm). Install once: npm i -g pnpm or corepack enable.

pnpm add -g sphereserver-mcp
# update later with:
pnpm up -g sphereserver-mcp

The server also performs a best-effort update check on startup (cached 24 h, non-blocking) and logs a one-line warning to stderr when a newer version is on npm. Disable with SPHEREMCP_SERVER_UPDATECHECK=false or server.updateCheck: false in ~/.sphereserver-mcp/config.yaml.

2. Build the knowledge index (one-time, ~10–30 min)

sphereserver-mcp init

This clones Source-X, Source-Archive, Scripts-X, vscode-scp-extension, fetches the wiki, parses SCP, computes embeddings, and writes a local SQLite + vector store under ~/.sphereserver-mcp/.

You can also run partial steps:

sphereserver-mcp init:repos       # git clones + parse
sphereserver-mcp init:wiki        # respectful wiki crawl
sphereserver-mcp init:changelogs  # mine commits for breaking changes
sphereserver-mcp init:discord     # ingest Discord exports / bot channels
sphereserver-mcp embed            # (re)compute embeddings

Invoking sphereserver-mcp with no arguments launches the MCP server over stdio — that's what your editor / agent does automatically.

3. Wire it into your MCP client

GitHub Copilot (VS Code)

VS Code automatically discovers sphereserver-mcp once it is installed globally — no settings.json changes needed. This relies on the MCP gallery, which is enabled by default in recent VS Code versions ("chat.mcp.gallery.enabled": true).

After installing, open the Copilot Chat panel and confirm the server is listed under MCP: List Servers (Ctrl+Shift+P).

If you prefer the always-latest pattern, register it manually in your user mcp.json instead of relying on the global install:

{
  "servers": {
    "sphereserver": {
      "command": "npx",
      "args": ["-y", "sphereserver-mcp@latest"]
    }
  }
}

Claude Code

claude mcp add sphereserver -- npx -y sphereserver-mcp@latest

Or in ~/.config/claude-code/mcp.json:

{
  "mcpServers": {
    "sphereserver": { "command": "npx", "args": ["-y", "sphereserver-mcp@latest"] }
  }
}

OpenCode

Always-latest (no global install needed):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "sphereserver-mcp": {
      "type": "local",
      "command": ["npx", "-y", "sphereserver-mcp@latest"],
      "enabled": true
    }
  }
}

Or, if you installed globally (pnpm add -g sphereserver-mcp):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "sphereserver-mcp": {
      "type": "local",
      "command": ["sphereserver-mcp"],
      "enabled": true
    }
  }
}

4. Ask away

"Generate a CHARDEF c_dragon_red for Sphere X with a @Death trigger that spawns a treasure chest, in modern style, strict mode."

"Migrate this 0.55i DIALOG to 56d and show me the diff."

"When did SRC. replace ARGO.? Cite the commit."

🛠️ Exposed MCP tools

✅ = implemented · 🟡 = preview (returns isError + fallback hint). See AGENTS.md for the agent-facing playbook.

| Tool | Status | Purpose | | -------------- | ------ | ---------------------------------------------------------- | | scp.search | ✅ | Semantic + lexical search across wiki + sources + scripts. | | scp.lookup | ✅ | Resolve a symbol (keyword / trigger / event / fn). | | scp.lint | ✅ | Static analysis, deprecation warnings, fix-its. | | scp.snippet | ✅ | Retrieve a curated snippet by tag (dialog, ai, timer…). | | repo.refresh | ✅ | Re-pull upstream sources and update the index. | | scp.generate | 🟡 | Generate SCP for a target version + style profile. | | scp.explain | 🟡 | Annotate a script block-by-block with citations. | | scp.migrate | 🟡 | Legacy → modern rewrite with unified diff. | | scp.compat | 🟡 | Cross-version compatibility report. | | scp.timeline | 🟡 | When did a feature appear / change / disappear? | | scp.docgen | 🟡 | Generate doc-comments for a script. |

The server also exposes MCP prompts (slash-commands in clients that support them): explain-scp, migrate-to-sphere-x, generate-itemdef, find-symbol.

See docs/tools.md for full schemas.

⚙️ Configuration

Defaults live in config/default.yaml. Override per-machine in ~/.sphereserver-mcp/config.yaml or via env (SPHEREMCP_*).

target:
  version: 'X' # 0.55 | 56d | X
  mode: modern # legacy | modern
  strict: true # reject deprecated syntax
  maxCompatibility: false # if true, generate code that runs on all 3 majors

rag:
  topK: 12
  rerank: true
  citations: true

embedding:
  provider: local # local (transformers.js) | openai | ollama
  model: BAAI/bge-small-en-v1.5
  dim: 384

ingest:
  wiki:
    baseUrl: https://wiki.spherecommunity.net
    rateLimitMs: 2000
    userAgent: 'sphereserver-mcp/0.1 (+https://github.com/ruben-feito/sphereserver-mcp)'
  repos:
    - { name: source-x, url: https://github.com/Sphereserver/Source-X, priority: 1 }
    - { name: source-archive, url: https://github.com/Sphereserver/Source-Archive, priority: 2 }
    - { name: source, url: https://github.com/Sphereserver/Source, priority: 3 }
    - { name: scripts-x, url: https://github.com/Sphereserver/Scripts-X, priority: 4 }
    - { name: vscode-scp, url: https://github.com/Sphereserver/vscode-scp-extension, priority: 6 }

🧱 Architecture (one paragraph)

A modular TypeScript monorepo: an ingestor (git clone + wiki crawl) feeds a SCP parser (Chevrotain) and a C++ light-parser that extract symbols, triggers and changelog deltas into a SQLite knowledge base; embeddings are produced locally (default: bge-small-en-v1.5 via transformers.js) and stored in SQLite (Float32 BLOBs, exact cosine). The MCP server (@modelcontextprotocol/sdk) exposes tools that combine lexical filters (version, scope, kind) with vector retrieval and a graph walker over a symbol ⇄ commit ⇄ wiki graph. All responses include version tags and source citations.

Full design in ARCHITECTURE.md. Roadmap in ROADMAP.md.

🗂️ Repository structure

sphereserver-mcp/
├── src/
│   ├── server/          # MCP server entry & tool registry
│   ├── tools/           # One file per MCP tool (generate, explain, …)
│   ├── parser/          # Chevrotain SCP parser, tokens, AST
│   ├── ingest/          # Git + wiki ingestors, changelog miner
│   ├── rag/             # Retrieval, reranking, citation assembly
│   ├── kb/              # SQLite schema, repositories, migrations
│   ├── embed/           # Embedding providers (local/openai/ollama)
│   ├── graph/           # Symbol/commit/wiki knowledge graph
│   ├── version/         # Version detection & compat matrix
│   ├── cli/             # `sphereserver-mcp init`… subcommands
│   ├── config/          # Config loader (yaml + env + zod)
│   └── util/            # logging, fs, fetch, rate-limit
├── config/              # Default YAML configs
├── schemas/             # JSON schemas for MCP tool I/O
├── docs/                # Architecture, tools, design notes
├── tests/               # vitest suites + SCP fixtures
├── .github/workflows/   # CI / release pipelines
├── LICENSE              # AGPL-3.0-or-later
├── NOTICE               # Third-party attributions
└── LEGAL.md             # Full licensing strategy

🤝 Contributing

See CONTRIBUTING.md. All commits must be DCO-signed (git commit -s). We use Conventional Commits and squash-merge.

🔐 Security

See SECURITY.md.

⚖️ License

Code: AGPL-3.0-or-later — see LICENSE. Third-party knowledge sources: retain their upstream licenses; see NOTICE and LEGAL.md.

This project is an independent community tool and is not affiliated with Electronic Arts, Origin Systems, or the SphereServer maintainers.