babylonjs-docs-mcp

An MCP (Model Context Protocol) server that exposes the BabylonJS 3D engine documentation to AI agents such as opencode, Claude Code, Cursor, etc.

Published as an npm package. With this server wired up, an agent you're chatting with can:

• browse the docs tree directory-by-directory (list_docs)
• read any page rendered as clean Markdown, frontmatter stripped (read_doc)
• search all 4,200+ pages with relevance-ranked full-text search (search_docs)
• subscribe to per-page resources (babylonjs://docs/{path})

The documentation has two families:

• API reference (api/) auto-generated by TypeDoc from the TypeScript source. Every class, interface, enumeration, function, type alias, and variable across all packages (@babylonjs/core, @babylonjs/gui, @babylonjs/loaders, @babylonjs/materials, @babylonjs/serializers).
• Guides & examples (examples/) hand-written tutorials and deep dives (cameras, lights, materials, meshes, particles, animations, physics, WebXR…).

Status

• Loads 4,200+ doc pages from the bundled docs/ snapshot.
• Speaks MCP over stdio (the standard local-server transport).
• Provides 3 tools, 1 resource template, and 1 ready-made prompt.
• Zero runtime deps beyond @modelcontextprotocol/sdk and zod.
• Lint + smoke-tested end-to-end.

Install

# Run once (downloads & caches the package)
npx -y babylonjs-docs-mcp

# Or install globally
npm install -g babylonjs-docs-mcp
babylonjs-docs-mcp

The server speaks JSON-RPC over stdio, so running the binary directly just waits for MCP messages on stdin point an MCP client at it (see below) rather than running it by hand.

From source

git clone https://github.com/VGFP/babylonjs-docs-mcp.git
cd babylonjs-docs-mcp
npm install
npm run build
node dist/index.js      # speaks JSON-RPC over stdio

You can sanity-check the server without an MCP-aware client:

npm run smoke       # node scripts/smoke-test.mjs  exercises every tool/resource
npm run lint        # node scripts/lint-preprocessed.mjs  validates preprocessing
npm test            # build + lint + smoke

Pointing an MCP client at it

opencode

Add the following to your project's .opencode/opencode.json (or ~/.config/opencode/opencode.json for global use):

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

If you installed it globally, the command can be just ["babylonjs-docs-mcp"]. For a local build, use the absolute path to dist/index.js:

{
  "mcp": {
    "babylonjs-docs-mcp": {
      "type": "local",
      "command": ["node", "/absolute/path/to/babylonjs-docs-mcp/dist/index.js"],
      "enabled": true
    }
  }
}

Restart opencode after saving the file MCP servers are loaded once at startup.

Other MCP clients (Claude Code, Cursor, etc.)

The server speaks standard MCP over stdio, so any compliant client works. Use npx -y babylonjs-docs-mcp or node /path/to/dist/index.js as the launch command.

Tools

list_docs

Browse the documentation tree directory-by-directory. Because the doc set has 4,200+ files, this returns the contents of a single directory (files + sub-directories with recursive file counts) rather than every page at once.

// Input
{ "path": "api/core/src/classes" }   // omit for the root directory

// Output (plain text, abbreviated)
// Contents of /api/core/src/classes (1261 items)
// ─────────────────────────────────────────
// 📄 AbortError  [api/core/src/classes/AbortError]
// 📄 AbstractActionManager  [api/core/src/classes/AbstractActionManager]
// 📄 Action  [api/core/src/classes/Action]
// ...

read_doc

Returns the full Markdown body of a single page, with YAML frontmatter stripped.

// Input
{ "path": "api/core/src/classes/Scene" }

// Output
// # Class: Scene
// *path: api/core/src/classes/Scene*
// ---
// Represents a scene to be rendered by the engine.
// ...full Markdown...

The path is relative to the docs root without the .md extension. A .md suffix is also accepted. Fuzzy matching (by filename or title) is used as a fallback if the exact path isn't found.

search_docs

Relevance-ranked full-text search. Title hits weighted highest, then headings, then body. Each hit includes a snippet around the first match.

// Input
{ "query": "WebXR", "limit": 5 }

// Output (truncated)
{
  "query": "WebXR",
  "total_hits": 47,
  "hits": [
    {
      "path": "api/core/src/classes/WebXRDefaultExperience",
      "title": "Class: WebXRDefaultExperience",
      "category": "api",
      "score": 112,
      "snippet": "...the default **WebXR** experience..."
    },
    ...
  ]
}

Resources

A single URI template is registered so clients can also use resources/read instead of tools/call if they prefer:

babylonjs://docs/{path}

Example:

{ "uri": "babylonjs://docs/api/core/src/classes/Scene" }

Prompts

| Name | Purpose | |---------------------|-------------------------------------------------------------------------| | babylonjs_overview| Returns a system-style primer describing BabylonJS + the doc structure.|

Configuration

| Env var | Default | Purpose | |--------------------------|----------------------------------------|----------------------------------| | BABYLONJS_DOCS_PATH | <package_root>/docs | Override the docs directory. | | BABYLONJS_DOCS_ROOT | (alias for the above) | Backward-compatible alias. |

Pointing BABYLONJS_DOCS_PATH at a fresh snapshot of the BabylonJS docs is the easiest way to pull in upstream changes the server reads at startup, so just restart it after updating.

Updating the bundled docs

The docs/ directory is a snapshot of BabylonJS's documentation, organised into two top-level directories:

• docs/api/ TypeDoc API reference (generated from source)
• docs/examples/ Guides, tutorials, and feature deep dives

Three scripts in scripts/ rebuild this snapshot from the upstream sources. They read the BabylonJS version from this package's version field (the -mcp.N suffix is stripped, so 9.13.0-mcp.1 regenerates docs for BabylonJS 9.13.0). The intermediate clones land in babylonjs-source/ and babylonjs-docs/ (both gitignored) so you can re-run the generator without re-cloning.

# One-shot: clone both sources, generate docs/, and run lint + smoke.
npm run docs:regenerate

# Or run the steps individually:
npm run docs:clone-source   # git clone Babylon.js monorepo at the version tag
npm run docs:clone-docs     # git clone BabylonJS Documentation repo (shallow)
npm run docs:generate       # TypeDoc API docs + copy examples -> docs/
npm run lint && npm run smoke   # validate the regenerated snapshot

When you're done, clean up the intermediate repos:

rm -rf babylonjs-source babylonjs-docs

Note: These scripts live in scripts/ but are not shipped with the npm package the files field in package.json is an allowlist (dist, docs, README.md, LICENSE), so published consumers only get the pre-built MCP server and the bundled docs/ snapshot.

If you only need to pull in upstream example changes (no API regeneration), skip TypeDoc and replace just docs/examples/:

git clone --depth 1 https://github.com/BabylonJS/Documentation.git upstream-examples
rm -rf docs/examples && cp -r upstream-examples/content docs/examples
rm -rf upstream-examples
npm run lint && npm run smoke

Releasing

Releases are automated via GitHub Actions. Pushing a v* tag triggers .github/workflows/release.yml, which builds and publishes to npm (with provenance). The NPM_TOKEN secret must be set in the repository's Actions secrets.

There are two release flows depending on whether the BabylonJS docs changed.

Version naming convention

Versions track the bundled BabylonJS docs snapshot, with an -mcp.N prerelease suffix to distinguish MCP-only releases against the same docs:

<major>.<minor>.<patch>-mcp.<n>     e.g. 9.13.0-mcp.1
└──────────┬───────────┘ └────┬───┘
   BabylonJS docs version   MCP release counter

• Bump the docs segment (e.g. 9.13.0 → 9.14.0) and reset -mcp.N to 1 when refreshing docs/ from a newer upstream BabylonJS release.
• Bump only the -mcp.N counter for MCP-only changes (tools, search, server logic) against the same docs snapshot.

Flow A New BabylonJS release (e.g. 9.13 9.14)

Use this when BabylonJS publishes a new version and you want to ship a fresh docs/ snapshot. Bump the version first the regen scripts derive the BabylonJS tag to check out from pkg.version (e.g. 9.14.0-mcp.1 BabylonJS 9.14.0).

# 1. Bump the MCP version: new docs segment, reset -mcp.N to 1.
npm version 9.14.0-mcp.1

# 2. Regenerate the docs/ snapshot (clones BabylonJS source @ 9.14.0 tag,
#    clones the Documentation repo, runs TypeDoc + copy, then lint + smoke).
npm run docs:regenerate

# 3. Commit the regenerated docs (step 1 already committed the version bump).
git add docs/ && git commit -m "docs: refresh snapshot to BabylonJS 9.14.0"

# 4. Clean up the intermediate clones (~GBs on disk, gitignored).
rm -rf babylonjs-source babylonjs-docs

# 5. Push. The v9.14.0-mcp.1 tag triggers release.yml.
git push --follow-tags

Flow B MCP-only release (e.g. 9.13.0-mcp.1 9.13.0-mcp.2)

Use this for changes to the server itself (tools, search, performance) that do not touch the bundled docs.

npm version prerelease --preid=mcp   # 9.13.0-mcp.1 -> 9.13.0-mcp.2
git push --follow-tags

Project layout

babylonjs-docs-mcp/
├── .github/workflows/
│   ├── ci.yml             # build + lint + smoke on push/PR
│   └── release.yml        # npm publish on version tags
├── docs/                  # All documentation pages (the data)
│   ├── api/               # TypeDoc API reference
│   └── examples/          # Guides, tutorials, feature deep dives
├── scripts/
│   ├── clone-babylonjs-source.sh   # Clone Babylon.js monorepo at version tag
│   ├── clone-babylonjs-docs.sh     # Clone BabylonJS Documentation repo
│   ├── generate-docs-for-mcp.sh    # TypeDoc + copy -> docs/
│   ├── regenerate-docs.sh          # End-to-end wrapper for the three above
│   ├── smoke-test.mjs              # End-to-end JSON-RPC exercise of every tool/resource
│   └── lint-preprocessed.mjs
├── src/
│   ├── index.ts           # MCP server registration + stdio transport
│   └── lib/
│       ├── docs.ts        # Doc discovery + Markdown preprocessor + index builder
│       └── search.ts      # Ranked full-text search
├── package.json
├── tsconfig.json
└── README.md

License

MIT.