babylon-mcp/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

A TypeScript-based Node.js project using Express.js for building a Babylon MCP server. The project uses ES modules and modern TypeScript standards.

Goals:

• Enable developers using babylonjs to quickly and easily search most current documentation for api documentation.
• Reduce token usage when using AI agents by having a canonical source for the framework and documentation.
• Enable developers to quickly and easily find sanbox examples
• Provide a mechanism to give feedback on how useful a particular result from the MCP server is for what they're trying to do
• Provide a mechanism to store feedback and use it to boost or lower probability of it being useful
• Provide a mechanism to collect feature enhancements or improvements and store them
• Provide a mechanism for users to see what other people have recommended and vote on the usefulness for them

Sources of information:

• Documentation https://github.com/BabylonJS/Documentation.git
• Babylon Source https://github.com/BabylonJS/Babylon.js.git
• Havok Physics https://github.com/BabylonJS/havok.git

Roadmap Progress Tracking

When updating ROADMAP.md to track progress:

• Use [X] to mark completed tasks
• Use [I] to mark tasks currently in progress
• Use [ ] for tasks not yet started

This provides a clear visual indicator of project status.

Development Commands

Unified Server (MCP + Web Interface)

• npm run dev - Start server in development mode with hot reload (tsx watch)
• npm run build - Compile TypeScript to JavaScript in dist/
• npm start - Run compiled server from dist/

Build & Testing

• npm run typecheck - Run TypeScript type checking without emitting files
• npm run clean - Remove the dist/ directory
• npm test - Run tests in watch mode
• npm run test:run - Run all tests once
• npm run test:ui - Run tests with interactive UI
• npm run test:coverage - Run tests with coverage report

The server runs on port 4000 by default and provides both MCP endpoints and web interface.

Architecture

Technology Stack

• Runtime: Node.js with ES modules
• Language: TypeScript 5.9+ with strict mode enabled
• MCP Server: @modelcontextprotocol/sdk v1.22+ (StreamableHTTPServerTransport)
• Web Framework: Express.js 5.x (integrated with MCP server)
• Build Tool: TypeScript compiler (tsc)
• Dev Tools: tsx (TypeScript executor with watch mode)
• Testing: Vitest 4.x with v8 coverage provider
• HTTP Testing: supertest for Express route testing
• Schema Validation: Zod v3.23.8 (compatible with MCP SDK)

TypeScript Configuration

• Target: ES2022 with NodeNext module resolution
• Strict Mode: All strict checks enabled including:
  • noUnusedLocals, noUnusedParameters
  • noUncheckedIndexedAccess
  • exactOptionalPropertyTypes
  • noImplicitOverride
• Module System: ES modules ("type": "module" in package.json)
• Output: Compiled files go to dist/ with source maps and declaration files

Project Structure

src/
  mcp/
    index.ts           - Main server entry point
    server.ts          - BabylonMCPServer class (MCP + Express integrated)
    config.ts          - Server configuration and metadata
    handlers.ts        - MCP tool handlers (search_babylon_docs, get_babylon_doc)
    routes.ts          - Express route definitions (/, /health, /mcp)
    transport.ts       - HTTP transport layer for MCP requests
    *.test.ts          - Co-located unit tests for each module
  __tests__/
    setup.ts           - Global test setup and teardown
    fixtures/          - Test fixtures (mock MCP requests, etc.)
  index.ts             - Re-exports for library usage
dist/                  - Compiled JavaScript output (gitignored)
vitest.config.ts       - Vitest test configuration

MCP Server Architecture

The MCP (Model Context Protocol) server is the primary interface for this application. It provides tools that AI agents can use to search and retrieve Babylon.js documentation.

Current MCP Tools

• search_babylon_docs: Search Babylon.js documentation

  • Input: query (string), optional category (string), optional limit (number)
  • Output: Ranked documentation results with snippets and links
  • Status: Placeholder implementation

• get_babylon_doc: Retrieve full documentation content

  • Input: path (string) - documentation file path or identifier
  • Output: Full documentation content optimized for AI consumption
  • Status: Placeholder implementation

MCP Server Details

• Transport: HTTP with StreamableHTTPServerTransport (stateless mode)
• Default Port: 4000
• Root Endpoint: http://localhost:4000/ (GET - server info)
• MCP Endpoint: http://localhost:4000/mcp (POST - JSON-RPC requests)
• Health Check: http://localhost:4000/health (GET request)
• Server Name: babylon-mcp
• Version: 1.0.0
• Location: src/mcp/server.ts
• Configuration: src/mcp/config.ts

The server is a unified Express + MCP application. It uses the official MCP SDK with StreamableHTTPServerTransport and implements the standard MCP protocol for tool listing and execution over HTTP POST requests with JSON-RPC.

Testing Strategy

Test Framework: Vitest

We use Vitest for unit testing due to its:

• Native ES modules and TypeScript support
• 10-20x faster than Jest
• Compatible API with Jest for easy migration
• Built-in coverage via v8

Test Organization

• Co-located tests: Each source file has a corresponding .test.ts file in the same directory
• AAA Pattern: Tests follow Arrange-Act-Assert structure
• Comprehensive mocking: All external dependencies (MCP SDK, Express, etc.) are properly mocked

Coverage Targets

• Lines: 80% minimum
• Functions: 80% minimum
• Branches: 75% minimum
• Statements: 80% minimum

Current coverage: 100% across all metrics ✓

Test Suites

1. config.test.ts (19 tests)

   • Server metadata validation
   • Capability definitions
   • Transport configuration
   • Source repository URLs

2. handlers.test.ts (18 tests)

   • MCP tool registration
   • search_babylon_docs handler (query, category, limit parameters)
   • get_babylon_doc handler (path parameter)
   • Zod schema validation
   • Response format compliance

3. routes.test.ts (12 tests)

   • Express middleware setup
   • Root endpoint (GET /)
   • Health check endpoint (GET /health)
   • MCP endpoint (POST /mcp)
   • 404 handling

4. transport.test.ts (9 tests)

   • StreamableHTTPServerTransport creation
   • Server connection lifecycle
   • Request handling
   • Response close listener
   • JSON-RPC error responses

5. server.test.ts (15 tests)

   • BabylonMCPServer construction
   • HTTP server startup (default and custom ports)
   • Graceful shutdown
   • SIGINT/SIGTERM signal handling

Running Tests

npm test              # Watch mode for development
npm run test:run      # Run once (CI/CD)
npm run test:ui       # Interactive UI
npm run test:coverage # Generate coverage report

Testing Best Practices

• Use TypeScript non-null assertions (!) in tests for cleaner code
• Mock external dependencies at module level
• Test both success and error paths
• Verify mock call counts and arguments
• Test edge cases (empty arrays, undefined values, errors)

Coding Standards

Naming Conventions

General Guidance

• Prefer short methods and files.
  • Functions shorter than 20 lines
  • Files smaller than 100 lines
• Prefer using third party libraries if generated code is going to exceed size standards.
  • Prompt to search npmjs and the internet to see if there are libraries that might meet our needs.
  • Think deeply and advise on tradeoffs for libraries (including popularity, update frequency, and any security vulnerabilityes)
  • Don't use libraries flagged as outdated or no longer maintained
  • Prefer libraries with fewer dependencies over those with many
• when selecting approaches, check documentation for deprecated code and research alternatives or new approaches.

• I'm ok with ! operator in test cases, but only use rarely in runtime code.