Babylon MCP Server

A Model Context Protocol (MCP) server that provides AI agents with access to Babylon.js documentation, API references, and source code through semantic search.

Overview

The Babylon MCP server enables AI assistants to:

• Search and retrieve Babylon.js documentation
• Query API documentation for classes, methods, and properties
• Search through Babylon.js source code
• Retrieve specific source code files or line ranges

This provides a canonical source for Babylon.js framework information, reducing token usage and improving accuracy when working with AI agents.

Features

• Documentation Search: Semantic search across Babylon.js documentation
• API Documentation: Search TypeScript API documentation with full TSDoc details
• Source Code Search: Vector-based semantic search through Babylon.js source code
• Source Code Retrieval: Fetch specific files or line ranges from the repository
• Local Repository Management: Automatically clones and updates Babylon.js repositories

Prerequisites

• Node.js 18 or higher
• npm or yarn
• ~2GB disk space for repositories and vector database

Installation

1. Clone this repository:

git clone <repository-url>
cd babylon-mcp

2. Install dependencies:

npm install

3. Build the project:

npm run build

Alpine Linux Setup

If you're running on Alpine Linux (musl libc), you need an additional setup step after installing dependencies:

npm install
npm run alpine:setup
npm run build

This removes the incompatible onnxruntime-node native module and configures the system to use the WASM backend instead. The WASM backend is slightly slower but works on all platforms.

Initial Setup

Before using the MCP server, you need to clone the Babylon.js repositories and index them. This is a one-time setup process.

Step 1: Clone Repositories

Clone the required Babylon.js repositories:

npm run clone:repos

This will clone:

• BabylonJS/Documentation (documentation site content)
• BabylonJS/Babylon.js (main framework source)
• BabylonJS/havok (physics engine)

Step 2: Index All Data (Recommended)

Run the master indexing script to index documentation, API, and source code:

npm run index:all

This will:

1. Index all documentation files (~5-10 minutes)
2. Index API documentation from TypeScript source (~10-15 minutes)
3. Index source code from core packages (~15-20 minutes)

Total indexing time: 30-45 minutes depending on your system.

Index Individual Components

You can also index components separately:

# Index documentation only
npm run index:docs

# Index API documentation only
npm run index:api

# Index source code only
npm run index:source

Running the Server

Development Mode

Run the server with hot reload:

npm run dev

Production Mode

npm start

The server runs on port 4000 by default.

Integration with AI Assistants

The Babylon MCP server uses HTTP transport and must be running before connecting AI assistants.

Starting the Server

First, start the MCP server:

# Development mode with hot reload
npm run dev

# OR production mode
npm start

The server runs on http://localhost:4000 by default.

Claude Desktop Configuration

To use this MCP server with Claude Desktop, add it to your Claude configuration file.

Configuration File Location

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Configuration

Add the following to your claude_desktop_config.json:

{
  "mcpServers": {
    "babylon-mcp": {
      "url": "http://localhost:4000/mcp"
    }
  }
}

Restart Claude Desktop

After updating the configuration, restart Claude Desktop for the changes to take effect.

Claude Code CLI Configuration

To use this MCP server with Claude Code (command line), use the CLI command to connect directly.

IMPORTANT: Ensure the MCP server is running before connecting (see "Starting the Server" section above).

CLI Usage

Connect to the MCP server using the /mcp command with the server URL:

# In Claude Code, connect to the running MCP server
/mcp http://localhost:4000/mcp

# Now you can use the tools
Search for "Vector3" in Babylon.js documentation

The /mcp command connects to the HTTP endpoint and makes the Babylon.js tools available in your session.

Note: Configuration file support for HTTP MCP servers is being investigated. Currently, use the CLI command above for the most reliable connection method.

Available MCP Tools

Once configured, Claude will have access to these tools:

1. search_babylon_docs

Search Babylon.js documentation with semantic search.

Parameters:

• query (string, required): Search query
• category (string, optional): Filter by category (e.g., "api", "tutorial")
• limit (number, optional): Maximum results (default: 5)

Example:

Search for "how to create a mesh" in Babylon.js documentation

2. get_babylon_doc

Retrieve full content of a specific documentation page.

Parameters:

• path (string, required): Documentation file path or identifier

Example:

Get the full documentation for "features/featuresDeepDive/mesh/creation"

3. search_babylon_api

Search Babylon.js API documentation (classes, methods, properties).

Parameters:

• query (string, required): API search query (e.g., "getMeshByName", "Scene")
• limit (number, optional): Maximum results (default: 5)

Example:

Search the API for "getMeshByName"

4. search_babylon_source

Search Babylon.js source code using semantic search.

Parameters:

• query (string, required): Search query for source code
• package (string, optional): Filter by package (e.g., "core", "gui")
• limit (number, optional): Maximum results (default: 5)

Example:

Search the source code for "mesh rendering implementation"

5. get_babylon_source

Retrieve full source code file or specific line range.

Parameters:

• filePath (string, required): Relative path from repository root
• startLine (number, optional): Start line number (1-indexed)
• endLine (number, optional): End line number (1-indexed)

Example:

Get the source code from "packages/dev/core/src/scene.ts" lines 4100-4110

Project Structure

babylon-mcp/
├── src/
│   ├── mcp/              # MCP server implementation
│   │   ├── index.ts      # Server entry point
│   │   ├── server.ts     # BabylonMCPServer class
│   │   ├── handlers.ts   # MCP tool handlers
│   │   └── ...
│   └── search/           # Search and indexing
│       ├── lancedb-search.ts        # Search implementation
│       ├── lancedb-indexer.ts       # Documentation indexer
│       ├── api-indexer.ts           # API indexer
│       ├── source-code-indexer.ts   # Source code indexer
│       └── ...
├── scripts/              # Indexing scripts
│   ├── index-docs.ts     # Index documentation
│   ├── index-api.ts      # Index API docs
│   └── index-source.ts   # Index source code
├── data/                 # Data directory (created during indexing)
│   ├── repositories/     # Cloned repositories
│   └── lancedb/          # Vector database
└── dist/                 # Compiled output

Development

Running Tests

# Run tests in watch mode
npm test

# Run tests once
npm run test:run

# Run tests with UI
npm run test:ui

# Run tests with coverage
npm run test:coverage

Type Checking

npm run typecheck

Building

npm run build

Data Storage

The server stores data in the ./data directory:

• ./data/repositories/: Cloned Git repositories (Documentation, Babylon.js, havok)
• ./data/lancedb/: Vector database containing indexed content

This directory will be approximately 1.5-2GB after full indexing.

Updating Data

To update the indexed data with the latest Babylon.js content:

1. The repositories are automatically updated during indexing
2. Re-run the indexing scripts:

npm run index:all

Troubleshooting

Server won't start

• Ensure port 4000 is available
• Check that the project has been built: npm run build
• Verify Node.js version is 18 or higher

Indexing fails

• Ensure you have internet connectivity (for cloning repositories)
• Check disk space (~2GB required)
• Try indexing components individually to isolate the issue

Claude doesn't see the tools

• Ensure the server is running: npm run dev or npm start
• Verify server is accessible: curl http://localhost:4000/health should return {"status":"healthy"...}
• Check configuration: Ensure ~/.claude/config.json or Claude Desktop config has the correct URL
• Restart Claude: Restart Claude Desktop or Claude Code after configuration changes
• Check server logs: Look for connection attempts in the server output

Search returns no results

• Ensure indexing has completed successfully
• Check that the ./data/lancedb directory exists and contains data
• Try re-indexing: npm run index:all

Architecture

The server uses:

• LanceDB: Vector database for semantic search
• Xenova/all-MiniLM-L6-v2: Transformer model for embeddings
• TypeDoc: For extracting TypeScript API documentation
• Express.js: Web server framework
• MCP SDK: Model Context Protocol implementation

Contributing

Contributions are welcome! Please ensure:

• All tests pass: npm test
• Type checking passes: npm run typecheck
• Code follows the project style

License

ISC

Resources

• Babylon.js Documentation
• Babylon.js Repository
• Model Context Protocol
• Claude Desktop