EraBasic reference MCP

EraBasic documentation reference server for MCP.

Requires Node.js 24 or newer. This single package includes binaries for Linux and macOS x64/arm64, and Windows x64. The launcher selects the matching bundled binary. Linux x64 is the locally execution-tested target; the others are cross-built, not certified by native execution.

MCP clients

Use era-docs-mcp@latest by default in command-based MCP configurations:

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

No arguments selects stdio. Standard output contains only MCP messages; diagnostics go to standard error. Clients that do not resolve npm command shims on Windows may need the explicit npx.cmd executable.

npx -y era-docs-mcp@latest --version
npx -y era-docs-mcp@latest stdio -index /path/to/reference.json.gz
npx -y era-docs-mcp@latest serve

@latest selects the release tagged latest. Restart an already-running MCP server to use a newly installed release; a running process does not update itself. If you need a fixed version instead, replace the package specifier with [email protected] to pin this release.

serve exposes Streamable HTTP at http://127.0.0.1:8080/mcp; configure that URL in an HTTP-capable MCP client. The npm wrapper does not expose the server publicly by default. No container or HTTPS proxy deployment configuration is included.

The three tools are search_reference, lookup_builtin, and read_reference. Read the full reference page before relying on a search excerpt. Both transports use the same tools and document snapshot.

Search and data

The package includes a compressed index containing the source Markdown, section metadata, lexical search data, and embedding vectors. Go, a repository checkout, and user-side indexing are not required. The installed package and the caller's working directory are not modified by serving.

Search attempts the local Ollama endpoint http://127.0.0.1:11434 with embeddinggemma:300m. If the service or a compatible model is unavailable, it falls back to BM25 and reports degradation in the tool result. Exact lookup and reference reads do not need Ollama. English lexical search is not equivalent to multilingual semantic retrieval; a Korean-only query can return no lexical matches.

For hybrid retrieval, explicitly install/start Ollama and pull the model yourself:

ollama pull embeddinggemma:300m
npx -y era-docs-mcp@latest stdio

The model digest and dimensions must match the packaged index. An incompatible model requires rebuilding the index; the server never silently reindexes. You can explicitly set -ollama URL, -model NAME, and -index FILE on stdio or serve. Queries are sent to the chosen embedding endpoint, not an answer-generation service. No models are automatically installed and no model weights are included.

Updating the npm package updates the bundled document snapshot. An explicit -index overrides that snapshot. index and eval remain developer commands and require their own source documents or evaluation cases; those inputs are not bundled.

Distribution license

Published npm packages are offered under the GNU Affero General Public License version 3 only (AGPL-3.0-only); each includes the full LICENSE text. This distribution license does not declare a license for the entire source repository. Third-party components retain their own licenses and notices. The embedding model uses the separate Gemma terms. Local reference runtime/game trees and model weights are excluded.

There are no platform dependencies or third-party Node runtime dependencies. Every installation includes all five binaries, so the download is larger than a platform-specific package. --omit=optional is supported. There is no postinstall downloader or runtime binary download fallback; a missing bundled executable reports a corrupt installation.