AI-XR-MCP: 3D WebGL Visualization for MCP

A Model Context Protocol (MCP) server providing interactive 3D WebGL visualizations for websites, GitHub repositories, and local file systems. Built in TypeScript with optimized configurations for various MCP clients.

This tool enables AI models like Claude to generate powerful 3D visualizations of code repositories, websites, and file systems. It's designed to work with the Model Context Protocol (MCP) standard, allowing any MCP-compatible AI assistant to access WebGL-powered visualizations.

Features

• 🚀 Full TypeScript support with strict type checking
• 🌐 Interactive 3D visualization using Three.js and force-directed graphs
• 🖥️ Visualize websites, GitHub repositories, and local directories
• ⚙️ Multiple layout algorithms: force-directed, radial, and hierarchical
• 📊 Flexible output formats: HTML, JSON, or data URLs
• 🧪 Complete test coverage with Vitest
• 🔌 Ready-to-use configurations for Claude Desktop, Windsurf Browser, and Cursor

Getting Started

Development

1. Install dependencies:

   npm install

2. Start the development server with hot reload:

   npm run dev

3. Build the project:

   npm run build

4. Run tests:

   npm test

5. Start the production server:

   npm start

Using with Claude CLI

1. Add this configuration to your ~/.claude/config.json:

   {
     "mcp": {
       "providers": {
         "webgl3d": {
           "description": "3D Visualization Tool",
           "url": "http://localhost:3000"
         }
       }
     }
   }

2. Launch Claude with the MCP provider:

   claude --mcp-provider webgl3d

3. Use the tool with commands like:

   /create3d https://example.com website
   

Project Structure

.
├── src/                # Source code
│   ├── index.ts        # Entry point
│   ├── tools/          # Tool implementations
│   │   ├── example.ts  # Example tool
│   │   └── webgl3d.ts  # 3D WebGL visualization tool
│   └── utils/          # Utility functions and types
├── configs/            # Client-specific configurations
│   ├── claude-desktop.json  # Claude Desktop config
│   ├── cursor.json     # Cursor Editor config
│   └── windsurf.json   # Windsurf Browser config
└── shortcuts/          # Command shortcuts
    └── webgl3d.json    # /create3d shortcut definition

WebGL 3D Visualization Tool

Generate interactive 3D visualizations for websites, GitHub repositories, or local directories using WebGL and force-directed graphs.

Tool Usage

{
  "name": "webgl-3d-visualization",
  "input": {
    "source": "https://example.com", 
    "sourceType": "website",
    "depth": 2,
    "layout": "force",
    "outputFormat": "html"
  }
}

Parameters

• source: URL of website, GitHub repository, or path to local directory
• sourceType: Type of source to visualize (website, github, or local)
• depth: How deep to scan (1-5, default: 2)
• layout: Layout algorithm to use (force, radial, or hierarchical, default: force)
• outputFormat: Format of visualization output (html, json, or url, default: html)

Visualization Examples

Website Structure

Creates a 3D graph showing the HTML structure of a website:

{
  "name": "webgl-3d-visualization",
  "input": {
    "source": "https://example.com",
    "sourceType": "website",
    "depth": 2
  }
}

GitHub Repository

Creates a 3D graph showing the file and directory structure of a GitHub repository:

{
  "name": "webgl-3d-visualization",
  "input": {
    "source": "https://github.com/username/repo",
    "sourceType": "github"
  }
}

Local Directory

Creates a hierarchical 3D graph showing the file and directory structure of a local folder:

{
  "name": "webgl-3d-visualization",
  "input": {
    "source": "/path/to/directory",
    "sourceType": "local",
    "depth": 3,
    "layout": "hierarchical"
  }
}

Shortcut Commands

Use the /create3d shortcut for quick access to the visualization tool:

/create3d [source] [sourceType] [layout] [depth]

Examples

# Visualize a website
/create3d https://example.com website

# Visualize a GitHub repository
/create3d https://github.com/username/repo github

# Visualize a local directory with hierarchical layout
/create3d /path/to/directory local hierarchical 3

Client Configurations

Claude Desktop

The configs/claude-desktop.json file configures the tool for Claude Desktop with optimized settings:

{
  "name": "AI-XR-MCP-3D-Visualization",
  "description": "Generate 3D WebGL visualizations of websites, repositories, and file structures",
  "tools": [
    {
      "name": "webgl-3d-visualization",
      "description": "Generate a 3D force-directed graph visualization for websites, GitHub repositories, or local file systems",
      "icon": "🌐",
      "preferredOutput": "html",
      "documentation": "Generates interactive 3D visualizations from websites, repositories, and directories"
    }
  ],
  "settings": {
    "defaultOutputFormat": "html",
    "maxDepth": 3
  }
}

To use:

1. Place the configuration file in the Claude Desktop MCP tools directory
2. Restart Claude Desktop to see the new tool

Windsurf Browser

The configs/windsurf_mcp_config.json file integrates the tool with the Windsurf browser extension:

{
  "servers": [
    {
      "id": "ai-xr-mcp-3d",
      "name": "3D Visualization Tool",
      "description": "Generate interactive 3D visualizations of web content and code repositories",
      "command": "npx example-mcp-tool",
      "type": "command",
      "enabled": true,
      "defaultTools": ["webgl-3d-visualization"],
      "config": {
        "serverName": "AI-XR-MCP-3D",
        "clientName": "WindSurf Browser AI",
        "tools": [
          {
            "name": "webgl-3d-visualization",
            "shortDescription": "Create 3D visualizations",
            "icon": "3d_rotation",
            "quickAccess": true
          }
        ],
        "permissions": {
          "fileSystem": { "read": true },
          "network": { "domains": ["*"] }
        }
      },
      "shortcuts": [
        {
          "name": "create3d",
          "description": "Create a 3D visualization",
          "command": "/create3d"
        }
      ]
    }
  ],
  "defaultServer": "ai-xr-mcp-3d",
  "settings": { "autoStart": true }
}

To use:

1. Import the configuration in the Windsurf extension settings
2. Enable the tool in the Windsurf AI menu

Cursor Editor

The configs/cursor.json file configures the tool for the Cursor code editor:

{
  "serverName": "XR-3D-Visualization",
  "serverDescription": "Generate interactive 3D visualizations for code analysis and exploration",
  "serverCommand": "npx example-mcp-tool",
  "tools": [
    {
      "name": "webgl-3d-visualization",
      "description": "Generate a 3D force-directed graph visualization for websites, GitHub repositories, or local file systems",
      "showInContext": true,
      "category": "Visualization",
      "icon": "construction",
      "allowedModels": ["*"]
    }
  ],
  "contextActions": [
    {
      "name": "Visualize Repository",
      "description": "Create a 3D visualization of the current repository structure",
      "tool": "webgl-3d-visualization",
      "defaultParams": {
        "sourceType": "local",
        "depth": 3,
        "layout": "hierarchical"
      },
      "showOn": ["repo", "directory"]
    }
  ],
  "configuration": {
    "autoStart": true,
    "debug": false
  }
}

To use:

1. Open Cursor settings
2. Go to the Features tab and navigate to MCP Servers section
3. Click "Add Server" and choose "Import from file"
4. Select the cursor.json file

Testing

Using TestClient

The TestClient allows for easy testing of tools:

import { TestClient } from "./utils/TestClient";

describe("WebGL3D", () => {
  const client = new TestClient();

  it("should process website correctly", async () => {
    const result = await client.callTool(
      "webgl-3d-visualization",
      { 
        source: "https://example.com", 
        sourceType: "website"
      }
    );
    expect(result.toolResult.content).toBeDefined();
  });
});

Using MCP Inspector

For visual debugging of your tools:

1. Start the inspector:

   npx @modelcontextprotocol/inspector node dist/index.js

2. Open the inspector UI at http://localhost:5173

Local Development with Cursor

To test your MCP server locally with Cursor:

1. Build and link the package:

   npm run build
   npm run link

2. Add the server to Cursor:

   • Use the provided configs/cursor.json file
   • Or manually add a new server pointing to npx example-mcp-tool

3. Verify the server starts correctly and test your visualizations

Use Cases

The WebGL 3D visualization tool can be used for:

• Code Structure Visualization: Explore complex codebases in 3D space to understand relationships between files and directories
• Website Analysis: Visualize website DOM structures to understand page composition and hierarchy
• Repository Exploration: Navigate GitHub repositories in an interactive 3D environment
• Dependency Mapping: Visualize relationships between components in large systems
• Educational Purposes: Create interactive 3D graphs for teaching software architecture concepts
• Data Presentation: Generate visually engaging representations of hierarchical data structures

How It Works

The tool leverages several key technologies to create interactive 3D visualizations:

1. Three.js: Provides WebGL-based 3D rendering capabilities
2. Force-directed graphs: Position nodes dynamically based on physics simulations
3. JSDOM: Parse website DOM structures for visualization
4. Octokit: Interface with GitHub API to access repository structures
5. Node.js file system API: Process local directory structures
6. MCP Protocol: Connect to AI models through a standardized interface

When processing a source (website, GitHub repo, or local directory), the tool:

1. Parses the structure into a graph data model with nodes and links
2. Applies a layout algorithm (force, radial, or hierarchical)
3. Generates an interactive HTML visualization with Three.js
4. Returns the visualization to the client

License

MIT