IWSDK RAG MCP Server

TypeScript-based Model Context Protocol (MCP) server that provides semantic code search across the Immersive Web SDK using RAG (Retrieval-Augmented Generation) with vector embeddings.

Overview

This MCP server exposes 8 specialized tools for AI assistants to search and understand IWSDK code:

1. search_code - Semantic search across all code
2. find_by_relationship - Find code by relationships (extends, implements, imports, calls)
3. get_api_reference - Look up specific APIs by name
4. get_file_content - Retrieve complete file contents
5. list_ecs_components - List all ECS components (27 components)
6. list_ecs_systems - List all ECS systems (17 systems)
7. find_dependents - Find code that depends on an API
8. find_usage_examples - Find real-world usage examples

What's Indexed

• 173 IWSDK chunks (27 ECS components, 17 systems)
• 3,164 dependency chunks (Three.js, WebXR types)
• 3,337 total searchable chunks with 768-dimensional embeddings
• Embedding model: sentence-transformers/all-mpnet-base-v2

Installation

Method 1: Install from npm/pnpm (Recommended)

# Using pnpm (recommended, matches IWSDK)
pnpm add -g @felixtz/iwsdk-rag-mcp

# Or using npm
npm install -g @felixtz/iwsdk-rag-mcp

Then add to Claude Code using the CLI (recommended):

# For user-level (available across all projects)
claude mcp add --transport stdio iwsdk-rag --scope user -- iwsdk-rag-mcp

# For project-level only
claude mcp add --transport stdio iwsdk-rag --scope local -- iwsdk-rag-mcp

Restart Claude Code, and the tools will be available!

Method 2: Use with npx (No Installation)

# For user-level (available across all projects)
claude mcp add --transport stdio iwsdk-rag --scope user -- npx -y @felixtz/iwsdk-rag-mcp

Method 3: Run from Source

# Clone and build
git clone https://github.com/felixtrz/iwsdk-rag-mcp.git
cd iwsdk-rag-mcp
pnpm install
pnpm run build

# Add to Claude Code
claude mcp add --transport stdio iwsdk-rag --scope user -- node /absolute/path/to/iwsdk-rag-mcp/dist/index.js

For Claude Desktop

Configuration file: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "iwsdk-rag": {
      "command": "iwsdk-rag-mcp"
    }
  }
}

Or with npx:

{
  "mcpServers": {
    "iwsdk-rag": {
      "command": "npx",
      "args": ["-y", "@felixtz/iwsdk-rag-mcp"]
    }
  }
}

Verify Installation

# List configured MCP servers
claude mcp list

# Should show:
# iwsdk-rag: iwsdk-rag-mcp - ✓ Connected

Usage Examples

Once installed, try asking Claude:

• "List all ECS components in IWSDK"
• "Show me how to use AudioSource"
• "Find examples of hand tracking in the codebase"
• "What classes extend Component?"
• "Show me the TransformSystem implementation"

Features

Semantic Search

• 768-dimensional embeddings using all-mpnet-base-v2
• Offline search - no external API calls required
• Fast results - all data loaded in memory

Smart Pattern Detection

• ECS Components: Automatically detected via createComponent() pattern (27 found)
• ECS Systems: Detected via extends createSystem() pattern (17 found)
• WebXR API Usage: Tracks XRSession, XRFrame, XRInputSource usage (63 chunks)
• Relationship Tracking: extends, implements, imports, calls

Complete Coverage

• IWSDK core packages (core, xr-input, locomotor, glxf)
• Three.js type definitions
• WebXR API types
• Full file content retrieval

Repository Structure

iwsdk-rag/
├── src/                   # TypeScript source code
│   ├── index.ts          # MCP server entry point
│   ├── search.ts         # Vector search service
│   ├── embeddings.ts     # Query embedding & similarity
│   ├── files.ts          # File content retrieval
│   └── tools/            # 8 MCP tool implementations
├── dist/                  # Compiled JavaScript
├── data/                  # Vector database
│   ├── chunks.json       # Pre-computed embeddings (83MB)
│   ├── metadata.json     # Database metadata
│   └── sources/          # Source files for get_file_content
├── src/
│   └── scripts/
│       └── ingest.ts     # TypeScript ingestion pipeline
├── package.json           # Package configuration
├── pnpm-lock.yaml         # pnpm lockfile
├── tsconfig.json          # TypeScript configuration
└── README.md              # This file

Development

Building from Source

git clone https://github.com/felixtrz/iwsdk-rag-mcp.git
cd iwsdk-rag-mcp
pnpm install
pnpm run build

Regenerating the Index

If you need to re-ingest the IWSDK codebase (e.g., after SDK updates):

npm run ingest

This will run the TypeScript ingestion pipeline to regenerate the vector database.

How It Works

Architecture

1. Ingestion (TypeScript): Parses TypeScript code using ts-morph, chunks semantically, generates embeddings
2. Storage: Pre-computed embeddings stored in JSON (~83MB)
3. MCP Server (TypeScript): Loads embeddings at startup, performs semantic search using transformers.js
4. AI Assistant: Uses MCP tools to search and understand the codebase

Vector Search Flow

1. User query → Embedded using all-mpnet-base-v2
2. Cosine similarity computed against all code chunk embeddings
3. Results ranked by similarity score
4. Optional filtering by source, type, relationships

Troubleshooting

Tools not showing up

1. Check config file location and syntax
2. Verify package is installed: pnpm list -g @felixtz/iwsdk-rag-mcp or npm list -g @felixtz/iwsdk-rag-mcp
3. Restart Claude Desktop/Code completely

Slow first load

• The embedding model (~420MB) downloads on first run
• Subsequent runs are faster (model is cached)

High memory usage

• Normal - the server loads 83MB of embeddings into memory for fast search
• Minimum recommended RAM: 2GB available

License

MIT License - Copyright (c) 2025 Felix Zhang

Links

• npm Package: https://www.npmjs.com/package/@felixtz/iwsdk-rag-mcp
• GitHub: https://github.com/felixtrz/iwsdk-rag-mcp
• Issues: https://github.com/felixtrz/iwsdk-rag-mcp/issues
• Author: Felix Zhang (https://github.com/felixtrz)
• Sponsor: https://github.com/sponsors/felixtrz

Credits

• Immersive Web SDK: https://github.com/facebook/immersive-web-sdk
• Model Context Protocol: https://modelcontextprotocol.io
• Embeddings: sentence-transformers/all-mpnet-base-v2