# CTS MCP Server

**Version**: 3.1.0  
**Protocol**: Model Context Protocol 2024-11-05  
**Status**: ✅ Production Ready

Model Context Protocol server for Close-to-Shore (CTS) methodology automation, providing automated task creation in Shrimp MCP and **interactive D3 artifact visualization** (signal maps, hop dashboards, dependency graphs) for Godot game development.

## Features

### Phase 3: Production-Ready Visualizations (v3.1.0 - NEW! 🎨)

- 🎯 **Real D3 Signal Maps**: Interactive force-directed graphs with signal relationship detection
  - Automatic clustering and community detection
  - Zoom, pan, drag, filter by EventBus/SignalBus
  - Lazy loading for large projects (>100 nodes)
  - Export to PNG/SVG/PDF
- 📊 **Hop Dashboard Renderer**: Gantt-style task progress visualization
  - Phase-based timeline with dependency arrows
  - Color-coded status (planned/in_progress/completed)
  - LOC budget tracking and CTS compliance stats
  - Progressive rendering for large projects (>10 hops)
- ⚡ **Performance Optimizations**:
  - <2s render time for large projects (200+ signals)
  - <500KB tree-shaken bundle size
  - <10MB memory growth over 10 renders
  - Lazy loading: Initial 50 nodes, +50 per "Load More"
- 🧪 **96 New Tests**: Full coverage for renderers, parsers, performance benchmarks
- 📚 **Comprehensive Documentation**: API reference, deployment guide, integration examples

### Tier 3 Infrastructure (v3.0.0)

- 🚀 **CI/CD Pipeline**: GitHub Actions with test, performance, quality, security jobs
- 📦 **NPM Package**: Scoped `@broken-divinity/cts-mcp-server` ready for npm publish
- 🐳 **Docker Support**: Multi-stage Alpine image (150-200MB), production-ready
- 📊 **Observability**: Structured logging, metrics collection, Prometheus export
- ⚡ **Performance**: All benchmarks passing (<2ms cache, <100ms config, <5ms sampling)
- 🧪 **Test Coverage**: 868+ tests passing (772 from v3.0.0 + 96 from Phase 3)

### Tier 2C Production Hardening (v3.0.0)

- 💾 **Result Caching**: LRU cache with SHA-256 hashing (<2ms operations, 29/29 tests ✅)
- ⚙️ **Hot-Reload Configuration**: JSON-based config with validation (28/28 tests ✅)
- 📏 **Stratified Sampling**: Efficient large dataset handling (<5ms small, <100ms large, 18/18 tests ✅)
- 🛡️ **Enhanced Error Handling**: Actionable CTSError types with recovery suggestions (10/10 tests ✅)
- ✅ **Schema Validation**: Zod schemas for all 9 tools (16/16 tests ✅)
- 🔧 **Tool Integration**: Consistent interface, cache support, metrics tracking (16/16 tests ✅)

### Phase 2 Enhancements (v2.0.0)

- 🎯 **AST-Level Parsing**: Tree-sitter-gdscript with 100% signal extraction accuracy
- 🌐 **Clustered Signal Maps**: Community detection with convex hull visualization (150-300 signals)
- 📊 **Dependency Graphs**: Cross-file signal connection tracking and visualization
- 📈 **Performance Trends**: Time-series monitoring of parse time, signal count, memory usage
- ⚡ **250x Faster Clustering**: 3ms for 150 nodes (greedy modularity optimization)
- 🧬 **20x Faster Parsing**: 12.5ms for 1K LOC files (tree-sitter WASM)

### Core Features

- �🚀 **Automated Task Creation**: Convert hop plans to Shrimp tasks via stdio IPC (30min → 5min per hop)
- 📊 **Signal Architecture Visualization**: D3.js force-directed graphs showing EventBus/SignalBus connections
- 📈 **CTS Compliance Dashboard**: React-based hop status boards with real-time progress tracking
- ⚡ **High Performance**: <50ms server startup, <400ms clustered map rendering
- 🧪 **Well-Tested**: 188 tests (93.6% pass rate), comprehensive coverage
- 🔒 **Secure**: Stdio transport, Zod validation, webview sandbox

## Quick Start

### Installation

```bash
cd cts_mcp
npm install
npm run build
```

**Note**: The server uses web-tree-sitter (WASM) for GDScript parsing. If the WASM file (`tree-sitter-gdscript.wasm`) is not available, the server will automatically fall back to a proven regex parser. See `docs/WASM_SETUP.md` for details.

### Usage

Start the MCP server (stdio transport):

```bash
node build/index.js
```

The server listens on stdin and writes to stdout using JSON-RPC 2.0 protocol.

## Tools

### 1. CTS_Export_to_Shrimp

Convert hop plan JSON to Shrimp tasks automatically.

**Input**:
```json
{
  "hopPlanJson": "{\"phases\":[{\"name\":\"Phase 1\",\"hops\":[{\"id\":\"1.1\",\"name\":\"Setup\",\"description\":\"Initialize project\",\"estimatedLOC\":200,\"dependencies\":[]}]}]}"
}
```

**Output**:
```json
{
  "success": true,
  "tasksCreated": 1,
  "taskIds": ["550e8400-e29b-41d4-a716-446655440000"]
}
```

**Example**:
```bash
echo '{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "CTS_Export_to_Shrimp",
    "arguments": {
      "hopPlanJson": "{\"phases\":[{\"name\":\"Phase 1\",\"hops\":[{\"id\":\"1.1\",\"name\":\"Setup Infrastructure\",\"description\":\"Initialize TypeScript project\",\"estimatedLOC\":200,\"dependencies\":[]}]}]}"
    }
  }
}' | node build/index.js
```

### 2. CTS_Render_Artifact

Render interactive D3 visualizations (signal maps, hop dashboards).

**Supported Artifact Types**:
- `signal_map`: Interactive force-directed signal graph with relationship detection
- `hop_dashboard`: Gantt-style CTS hop progress visualization

**Signal Map Example**:
```bash
echo '{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "CTS_Render_Artifact",
    "arguments": {
      "artifactType": "signal_map",
      "data": {
        "signals": [
          {"name": "player_health_changed", "source": "EventBus", "params": ["new_health", "old_health"], "filePath": "scripts/player.gd", "line": 42},
          {"name": "enemy_spawned", "source": "EventBus", "params": ["enemy_type", "position"], "filePath": "scripts/enemy_manager.gd", "line": 105}
        ],
        "projectPath": "/path/to/project"
      },
      "metadata": {
        "title": "Player & Combat Signals",
        "description": "Core gameplay signal architecture"
      }
    }
  }
}' | node build/index.js
```

**Features**:
- 🎯 **Force-Directed Layout**: Nodes repel, edges attract, clusters group
- 🖱️ **Interactive Controls**: Zoom, pan, drag nodes, filter by EventBus/SignalBus
- ⚡ **Lazy Loading**: Automatic for graphs >100 nodes (initial batch: 50 nodes)
- 🎨 **Dark/Light Themes**: Automatic theme detection (respects VS Code theme)
- 📦 **Export**: PNG/SVG/PDF via browser APIs (see docs/API.md)
- 🔍 **Signal Search**: Filter by name, file, or type

**Hop Dashboard Example**:
```bash
echo '{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "CTS_Render_Artifact",
    "arguments": {
      "artifactType": "hop_dashboard",
      "data": {
        "phases": [
          {
            "name": "Phase 1: Foundation",
            "hops": [
              {
                "id": "1.1a",
                "name": "Project Setup",
                "status": "completed",
                "description": "Initialize Godot project",
                "estimatedLOC": 200,
                "actualLOC": 185,
                "ctsCompliant": true,
                "phase": "Phase 1: Foundation",
                "dependencies": []
              },
              {
                "id": "1.2a",
                "name": "Signal Architecture",
                "status": "in_progress",
                "description": "Implement EventBus",
                "estimatedLOC": 300,
                "ctsCompliant": true,
                "phase": "Phase 1: Foundation",
                "dependencies": ["1.1a"]
              }
            ]
          }
        ]
      },
      "metadata": {
        "title": "Project Roadmap"
      }
    }
  }
}' | node build/index.js
```

**Features**:
- 📊 **Gantt Timeline**: Horizontal phase-based layout
- 🎨 **Status Colors**: Planned (gray), in_progress (blue), completed (green)
- ➡️ **Dependency Arrows**: Left-to-right flow with curved paths
- 📈 **Stats Panel**: Completion rate, LOC budget, CTS compliance
- 🔄 **Progressive Rendering**: Automatic for dashboards >10 hops (yields to main thread)

### 3. CTS_Scan_Project_Signals

Scan Godot project for EventBus/SignalBus signal definitions and optionally render signal map.

**Input**:
```json
{
  "projectPath": "/home/user/Godot/MyProject",
  "renderMap": true
}
```

**Output**:
```json
{
  "success": true,
  "timestamp": "2025-11-04T15:30:00Z",
  "toolName": "CTS_Scan_Project_Signals",
  "result": {
    "projectPath": "/home/user/Godot/MyProject",
    "totalSignals": 55,
    "eventBusSignals": 42,
    "signalBusSignals": 13,
    "signals": [
      {"name": "player_health_changed", "source": "EventBus", "params": ["new_health", "old_health"], "file": "scripts/player.gd", "line": 42}
    ],
    "rendered": true,
    "html": "<!DOCTYPE html>...",
    "cached": false
  }
}
```

**Performance**:
- ~500ms scan time for 1000-file projects
- <100ms render for small projects (<50 signals)
- <2s render for large projects (>500 signals) with lazy loading

## Documentation

- 📖 **[API Reference](docs/API.md)**: Comprehensive API documentation for all tools, artifact types, and renderer APIs
- 🚀 **[Deployment Guide](docs/DEPLOYMENT.md)**: Production deployment strategies (systemd, PM2, Docker)
- 🧪 **[Integration Examples](docs/API.md#code-examples)**: Full code examples for signal scanning, artifact rendering, export

## Quick Start

### Installation

```bash
cd cts_mcp
npm install
npm run build
```

**Verify Installation**:
```bash
npm test
# Expected: 868+ tests passing
```

### Enable Production Renderers

```bash
export CTS_EXPERIMENTAL_MCP_UI=true
npm start
```

The server listens on **stdin** and writes to **stdout** using JSON-RPC 2.0 protocol.

### VS Code Integration

Add to `.vscode/settings.json`:

```json
{
  "mcpServers": {
    "cts": {
      "command": "node",
      "args": ["/path/to/cts_mcp/build/index.js"],
      "env": {
        "CTS_EXPERIMENTAL_MCP_UI": "true"
      }
    }
  }
}
```

### Claude Desktop Integration

Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "cts": {
      "command": "node",
      "args": ["/path/to/cts_mcp/build/index.js"],
      "env": {
        "CTS_EXPERIMENTAL_MCP_UI": "true"
      }
    }
  }
}
```

## Examples

### Example 1: Render Signal Map

```bash
# 1. Create test data
cat > test_signals.json << 'EOF'
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "CTS_Render_Artifact",
    "arguments": {
      "artifactType": "signal_map",
      "data": "{\"signals\":[{\"name\":\"player_health_changed\",\"file\":\"autoload/EventBus.gd\",\"line\":5,\"connections\":[{\"file\":\"ui/HealthBar.gd\",\"line\":12},{\"file\":\"components/HealthComponent.gd\",\"line\":45}]},{\"name\":\"player_died\",\"file\":\"autoload/EventBus.gd\",\"line\":6,\"connections\":[{\"file\":\"scenes/GameManager.gd\",\"line\":78},{\"file\":\"ui/DeathScreen.gd\",\"line\":23}]}],\"filters\":{}}"
    }
  }
}
EOF

# 2. Render and save HTML
cat test_signals.json | node build/index.js 2>/dev/null | jq '.result.content[0].text' -r | jq -r '.html' > signal_map.html

# 3. Open in browser
xdg-open signal_map.html
```

**Result**: Interactive D3.js force-directed graph with 2 signals and 4 connections.

### Example 2: Render Hop Dashboard

```bash
# 1. Create test data
cat > test_hops.json << 'EOF'
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "CTS_Render_Artifact",
    "arguments": {
      "artifactType": "hop_dashboard",
      "data": "{\"phases\":[{\"name\":\"Phase 1: Foundation\",\"hops\":[{\"id\":\"5.1a\",\"name\":\"MCP Core Infrastructure\",\"status\":\"completed\",\"estimatedLOC\":400,\"actualLOC\":421,\"ctsCompliant\":true,\"dependencies\":[],\"testCoverage\":85},{\"id\":\"5.1b\",\"name\":\"Artifact Visualizations\",\"status\":\"in_progress\",\"estimatedLOC\":350,\"actualLOC\":294,\"ctsCompliant\":true,\"dependencies\":[\"5.1a\"],\"testCoverage\":78}]}],\"statistics\":{\"totalLOC\":715,\"plannedLOC\":750,\"complianceRate\":100,\"completionRate\":50}}"
    }
  }
}
EOF

# 2. Render and save HTML
cat test_hops.json | node build/index.js 2>/dev/null | jq '.result.content[0].text' -r | jq -r '.html' > hop_dashboard.html

# 3. Open in browser
xdg-open hop_dashboard.html
```

**Result**: Interactive React dashboard with 2 hops, status filtering, and statistics panel.

### Example 3: Export to Shrimp (Requires Shrimp MCP Running)

```bash
# 1. Start Shrimp MCP server (in separate terminal)
# (Follow Shrimp MCP setup instructions)

# 2. Create hop plan
cat > hop_plan.json << 'EOF'
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "CTS_Export_to_Shrimp",
    "arguments": {
      "hopPlanJson": "{\"phases\":[{\"name\":\"Phase 1: Setup\",\"hops\":[{\"id\":\"1.1\",\"name\":\"Initialize TypeScript Project\",\"description\":\"Create package.json, tsconfig.json, and src structure\",\"estimatedLOC\":200,\"dependencies\":[]},{\"id\":\"1.2\",\"name\":\"Implement MCP Server\",\"description\":\"Create server.ts with stdio transport and protocol handlers\",\"estimatedLOC\":300,\"dependencies\":[\"1.1\"]}]}]}"
    }
  }
}
EOF

# 3. Export to Shrimp
cat hop_plan.json | node build/index.js

# 4. Check Shrimp for created tasks
# (Use Shrimp CLI or UI to view tasks)
```

**Result**: 2 tasks created in Shrimp with dependencies configured.

## GDScript Integration

The CTS MCP server can be called from Godot GDScript using the `BDMCPClient` from the `bd_dev_tools` addon.

### Prerequisites

1. Install `bd_dev_tools` addon (contains `BDMCPClient`)
2. Build the CTS MCP server: `npm run build`
3. Ensure CTS MCP binary is accessible at `cts_mcp/build/index.js`

### Quick Start

```gdscript
extends Node

var mcp_client: BDMCPClient

func _ready() -> void:
    # Initialize MCP client
    mcp_client = BDMCPClient.new()
    add_child(mcp_client)
    
    # Register CTS MCP server
    var error := CTSMCPConfig.register_cts_server(mcp_client)
    if error != OK:
        push_error("Failed to register CTS MCP server: ", error)
        return
    
    # Connect to server (starts stdio subprocess)
    error = CTSMCPConfig.connect_to_cts_server(mcp_client)
    if error != OK:
        push_error("Failed to connect to CTS MCP server: ", error)
        return
    
    print("✅ CTS MCP server ready!")
    
    # Example: Export hop plan to Shrimp
    _export_example_hop()

func _export_example_hop() -> void:
    var hop_plan := {
        "phases": [{
            "name": "Phase 1: Foundation",
            "hops": [{
                "id": "1.1",
                "name": "Setup TypeScript Project",
                "description": "Initialize npm project with TypeScript config",
                "estimatedLOC": 200,
                "dependencies": []
            }]
        }]
    }
    
    var response := CTSMCPConfig.call_export_to_shrimp(
        mcp_client,
        hop_plan,
        "append",  # updateMode: append, overwrite, selective, clearAllTasks
        true       # generateSubTasks
    )
    
    if response.has("error"):
        push_error("❌ Export failed: ", response.error.message)
        return
    
    print("✅ Tasks created: ", response.content.tasksCreated)
    print("📋 Task IDs: ", response.content.taskIds)
```

### API Reference

#### CTSMCPConfig.register_cts_server(client: BDMCPClient) -> Error

Registers the CTS MCP server configuration with the MCP client.

**Parameters**:
- `client`: BDMCPClient instance

**Returns**: `Error` enum (OK or error code)

**Example**:
```gdscript
var error := CTSMCPConfig.register_cts_server(mcp_client)
if error != OK:
    push_error("Registration failed: ", error)
```

#### CTSMCPConfig.connect_to_cts_server(client: BDMCPClient) -> Error

Connects to the CTS MCP server (starts stdio subprocess).

**Parameters**:
- `client`: BDMCPClient instance (must be registered first)

**Returns**: `Error` enum (OK or error code)

**Example**:
```gdscript
var error := CTSMCPConfig.connect_to_cts_server(mcp_client)
if error != OK:
    push_error("Connection failed: ", error)
```

#### CTSMCPConfig.call_export_to_shrimp(client: BDMCPClient, hop_plan: Dictionary, update_mode: String, generate_sub_tasks: bool) -> Dictionary

Exports a hop plan to Shrimp MCP as tasks.

**Parameters**:
- `client`: BDMCPClient instance (must be connected)
- `hop_plan`: Hop plan dictionary (see schema below)
- `update_mode`: Task update mode (`"append"`, `"overwrite"`, `"selective"`, `"clearAllTasks"`)
- `generate_sub_tasks`: Whether to split hops into subtasks

**Returns**: Dictionary with keys:
- `content`: `{ tasksCreated: int, taskIds: Array, details: Array }`
- `error`: `{ code: String, message: String }` (if failed)

**Hop Plan Schema**:
```gdscript
{
    "phases": [
        {
            "name": "Phase Name",
            "hops": [
                {
                    "id": "1.1",
                    "name": "Hop Name",
                    "description": "Hop description",
                    "estimatedLOC": 200,
                    "dependencies": ["0.9"]  # Optional
                }
            ]
        }
    ]
}
```

**Example**:
```gdscript
var response := CTSMCPConfig.call_export_to_shrimp(
    mcp_client,
    {"phases": [...]},
    "append",
    true
)
print("Tasks created: ", response.content.tasksCreated)
```

### Advanced Usage

**Call other CTS tools directly:**

```gdscript
# CTS_Scan_Project_Signals
var scan_args := {
    "projectPath": "/home/user/Godot/MyProject",
    "includeEventBusOnly": true
}
var scan_response := mcp_client.call_tool("cts_mcp", "CTS_Scan_Project_Signals", scan_args)
print("Signals found: ", scan_response.content.signalsFound)

# CTS_Render_Artifact (Signal Map V2)
var artifact_args := {
    "artifactType": "signal_map_v2",
    "data": JSON.stringify({
        "signals": scan_response.content.data.signals,
        "filters": {}
    })
}
var artifact_response := mcp_client.call_tool("cts_mcp", "CTS_Render_Artifact", artifact_args)
print("Artifact HTML saved to: ", artifact_response.content.filePath)
```

### Error Handling

```gdscript
# Check if CTS MCP server is available before calling
var error := CTSMCPConfig.register_cts_server(mcp_client)
if error == ERR_FILE_NOT_FOUND:
    push_error("CTS MCP server not built. Run: cd cts_mcp && npm run build")
    return
elif error != OK:
    push_error("Failed to register CTS MCP server: ", error)
    return

# Handle tool call errors
var response := mcp_client.call_tool("cts_mcp", "CTS_Export_to_Shrimp", arguments)
if response.has("error"):
    push_error("Tool call failed: ", response.error.message)
    push_error("Error code: ", response.error.code)
```

### Debugging

Enable debug logging in `BDMCPClient`:

```gdscript
# In autoload/EventBus.gd or your initialization script
EventBus.mcp_debug_enabled = true

# Now all MCP communication will be logged:
# [MCP] Sending request: {"jsonrpc":"2.0",...}
# [MCP] Received response: {"result":...}
```

Check CTS MCP server logs:

```bash
# Run CTS MCP server manually to see logs
node build/index.js

# Send test request
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | node build/index.js
```

### Testing

The CTS MCP integration is validated by GUT tests in `test/cts_mcp/test_cts_mcp_client.gd`.

**Run tests via Godot Editor:**
1. Open Godot Editor: `godot4 --path /home/eric/Godot/ProtoBd --editor`
2. Navigate to: Bottom Panel → GUT → Run Tests
3. Select `test/cts_mcp/test_cts_mcp_client.gd` in the test list
4. Click "Run" button
5. View results in GUT panel

**Test Coverage:**
- Server registration and connection
- Tool list retrieval
- CTS_Export_to_Shrimp calls with various hop plans
- Error handling (invalid arguments, server unavailable)
- Response validation (schema compliance)

**Example test structure:**
```gdscript
godot4 --path . --headless -s addons/gut/gut_cmdln.gd -gtest=res://test/cts_mcp/

# Or use the GUT panel in Godot Editor
# Navigate to: Bottom Panel -> GUT -> Select test/cts_mcp/test_cts_mcp_client.gd -> Run
```

Expected test results:
- ✅ `test_cts_server_registration` - Registers server successfully
- ✅ `test_cts_connection` - Connects to server
- ✅ `test_list_cts_tools` - Lists 9+ tools (CTS_Export_to_Shrimp, CTS_Render_Artifact, etc.)
- ✅ `test_call_export_to_shrimp` - Calls tool and receives response
- ✅ `test_error_handling_missing_binary` - Handles missing binary gracefully
- ✅ `test_connection_timeout` - Handles connection timeout
- ✅ `test_server_lifecycle` - Full lifecycle (register, connect, disconnect)

## Architecture

### Technology Stack

- **Runtime**: Node.js 20+
- **Language**: TypeScript 5.0 (strict mode)
- **Protocol**: Model Context Protocol (stdio transport)
- **Validation**: Zod 3.22
- **Visualization**: D3.js 7 (CDN), React 18 (CDN)
- **Testing**: Jest 29.7

### Project Structure

```
cts_mcp/
├── src/
│   ├── index.ts                # Entry point (stdio transport)
│   ├── server.ts               # MCP server (protocol handlers)
│   ├── types.ts                # TypeScript interfaces
│   ├── parser/
│   │   ├── tree_sitter_bridge.ts    # WASM tree-sitter integration (Phase 2)
│   │   ├── signal_extractor.ts      # AST signal extraction (Phase 2)
│   │   └── parser_diagnostics.ts    # Regression testing (Phase 2)
│   ├── artifacts/
│   │   ├── artifact_engine.ts       # Renderer routing + caching
│   │   ├── metadata.ts              # Versioning system (Phase 2)
│   │   ├── types.ts                 # Artifact schemas
│   │   ├── clustering/
│   │   │   └── community_detection.ts  # Greedy modularity (Phase 2)
│   │   ├── parsers/
│   │   │   └── gdscript_parser.ts   # Signal extraction (Phase 1)
│   │   └── renderers/
│   │       ├── d3_signal_map.ts           # Basic force-directed (Phase 1)
│   │       ├── d3_signal_map_v2.ts        # Clustered map (Phase 2)
│   │       ├── dependency_graph.ts        # Connection tracking (Phase 2)
│   │       ├── performance_trends.ts      # Time-series (Phase 2)
│   │       └── react_hop_dashboard.ts     # React dashboard (Phase 1)
│   ├── metrics/
│   │   └── performance_pipeline.ts  # Trend data collection (Phase 2)
│   ├── tools/
│   │   ├── cts_export_to_shrimp.ts  # Shrimp integration
│   │   ├── render_artifact.ts       # Artifact tool
│   │   └── scan_project_signals.ts  # Signal scanner
│   └── integrations/
│       └── webview_manager_template.ts  # VS Code webview
├── test/
│   ├── __tests__/                   # Jest tests (188 total)
│   │   ├── tree_sitter_bridge.test.ts (12 tests)
│   │   ├── signal_extractor.test.ts (15 tests)
│   │   ├── parser_diagnostics.test.ts (30 tests)
│   │   ├── clustered_signal_map.test.ts (19 tests)
│   │   └── ... (other test files)
│   └── fixtures/
│       ├── *.gd                     # GDScript test files (20 files)
│       └── ground_truth/*.json      # Expected extraction results
├── docs/
│   ├── signals/
│   │   └── PHASE_2_SIGNAL_CONTRACTS.md
│   ├── architecture/decisions/
│   │   ├── ADR_TREE_SITTER_ADOPTION.md
│   │   └── ADR_CLUSTERING_STRATEGY.md
│   ├── guides/
│   │   └── PHASE_2_MIGRATION.md
│   └── PHASE_CTS_MCP_2_COMPLETION_REPORT.md
├── scripts/
│   └── benchmark_clustering.js      # Performance benchmarks
├── build/                           # Compiled JavaScript
├── package.json
├── tsconfig.json
└── jest.config.cjs
```

### Performance

| Metric | Target | Actual (Phase 2) | Status |
|--------|--------|------------------|--------|
| Server Startup | <2s | 46ms | ✅ 97.7% faster |
| Tool Routing | <100ms | 1-2ms | ✅ |
| Signal Parsing (1K LOC) | <250ms | 12.5ms | ✅ 20x faster |
| Signal Map (Basic, 50 nodes) | <500ms | 180ms | ✅ |
| Signal Map (Clustered, 150 nodes) | <1000ms | 400ms | ✅ 2.5x faster |
| Clustering (150 nodes) | <750ms | 3ms | ✅ 250x faster |
| Dependency Graph (150 nodes) | <800ms | 300ms | ✅ |
| Performance Trends (1K samples) | <500ms | 250ms | ✅ |
| Cache Lookup | <10ms | <1ms | ✅ |

## Development

### Build

```bash
npm run build          # Compile TypeScript → JavaScript
npm run dev            # Development mode (no build)
```

### Testing

```bash
npm test               # Run all tests
npm run test:coverage  # Run with coverage report
npm run test:watch     # Watch mode
```

**Test Results**:
- ✅ 23/23 tests passing (100% pass rate)
- ✅ 85% functional coverage
- ✅ <2s test execution time

### Code Quality

```bash
tsc --noEmit          # Type checking
npm run build         # Compilation (0 errors)
```

## Configuration

### Environment Variables

- `DEBUG=true` - Enable verbose logging
- `SHRIMP_MCP_PATH=/path/to/shrimp/build/index.js` - Custom Shrimp path

### Cache Configuration

Default cache settings in `src/artifacts/artifact_engine.ts`:

```typescript
private maxCacheSize = 50;  // Max artifacts cached
private maxCacheAge = 3600000;  // 1 hour (unused, artifacts are immutable)
```

## Troubleshooting

### Issue: "Shrimp MCP not found"

**Cause**: CTS_Export_to_Shrimp cannot reach Shrimp MCP server

**Solution**:
1. Ensure Shrimp MCP server is running
2. Check Shrimp path configuration
3. Verify stdio IPC permissions

### Issue: Artifact render timeout

**Cause**: Large dataset (100+ signals) exceeds render budget

**Solution**:
1. Filter signals before rendering (use `includeEventBusOnly: true`)
2. Increase timeout in VS Code extension
3. Phase 2 will add graph clustering

### Issue: TypeScript compilation errors

**Cause**: Missing type definitions or syntax errors

**Solution**:
```bash
npm install          # Ensure dependencies installed
npm run build        # Check for specific errors
```

## Documentation

### Guides
- **[MCP Server Guide](docs/MCP_SERVER_GUIDE.md)** - Complete usage guide with installation, configuration, and all tool documentation
- **[API Reference](docs/API_REFERENCE.md)** - Comprehensive API documentation with schemas, types, and examples
- **[Troubleshooting Guide](docs/TROUBLESHOOTING.md)** - Common issues and solutions

### Infrastructure
- **[CI/CD Pipeline](docs/CI_CD_PIPELINE.md)** - GitHub Actions workflow, benchmarks, coverage
- **[Packaging Guide](docs/PACKAGING.md)** - NPM publishing and Docker deployment procedures

### Technical Details
- **[Tier 2C Improvements](docs/TIER_2C_IMPROVEMENTS.md)** - Production hardening documentation (caching, config, sampling, errors, schemas)
- **[Phase 2 Migration](docs/guides/PHASE_2_MIGRATION.md)** - Upgrade guide from v1.0 to v2.0
- **[VS Code MCP Setup](docs/VSCODE_MCP_SETUP.md)** - VS Code integration configuration
- **[WASM Setup](docs/WASM_SETUP.md)** - Tree-sitter WASM configuration

### Architecture Decision Records
- **[ADR: Tree-sitter Adoption](docs/architecture/decisions/ADR_TREE_SITTER_ADOPTION.md)**
- **[ADR: Clustering Strategy](docs/architecture/decisions/ADR_CLUSTERING_STRATEGY.md)**
- **[ADR: Sandpack Deferral](docs/architecture/decisions/ADR_SANDPACK_PHASE_3.md)**
- **[ADR: D3.js Signal Map](docs/architecture/decisions/ADR_D3_SIGNAL_MAP.md)**

### Project Documentation
- **[Test Results](./TEST_RESULTS.md)** - Comprehensive test coverage report
- **[CHANGELOG](./CHANGELOG.md)** - Version history and release notes

## Contributing

See [CONTRIBUTING.md](../CONTRIBUTING.md) for development guidelines.

## License

MIT License - See [LICENSE.txt](../LICENSE.txt)

## Changelog

### v3.0.0 (October 31, 2025)

**Tier 0 & Tier 1 Complete** ✅ - Template-First MCP Development

- ✅ **New Tools**: Added 4 tools using template-first design:
  - CTS_Reasoning (template-driven iteration, 750 LOC)
  - CTS_Bughunter (search + heuristic scan, 720 LOC)
  - CTS_Cleanup (filesystem tidy, 740 LOC)
  - CTS_Audit_Project (compliance checks, 740 LOC)
- ✅ **Tree-Sitter Fix**: Migrated to WASM (`web-tree-sitter`)
  - Unblocked 3 tools: scan_project_signals, analyze_project, suggest_refactoring
  - AST parsing with caching (<50ms per file, <1ms cached)
  - Headless CI/CD compatible (no native module compilation)
- ✅ **MCP Tool Templates** (Tier 0):
  - TypeScript template: 460 lines, 5 sections (Zod, MCPError, logging, performance tracking)
  - Rust template: 483 lines, 5 sections (safe mutex, tracing, async/await)
  - Template compliance audit: 13 tools scored (avg 64/100, max 90/100)
- ✅ **Architecture Enhancements**:
  - Signal contracts (Section 10): Cross-MCP data flow schemas
  - Performance budgets (Section 11): <100ms sync tools, <5s async tools
  - Integration topology (Section 12): Coordinator pattern documentation
- ✅ **GDScript Integration**: MCPClient for CTS tool calling from Godot
- ✅ **Breaking Changes**:
  - Requires Node.js 18+ (ESM modules, WASM support)
  - tree-sitter → web-tree-sitter (native bindings removed)
  - 9 total tools (5 existing + 4 new)

**Metrics**:
- Total Tools: 9 (5 existing + 4 new template-based)
- Total LOC: ~4,500 (implementation) + ~1,200 (tests)
- Performance: All tools meet <100ms sync / <5s async budgets
- CTS Compliance: 100% (all files <500 lines)
- Template Compliance: 90% (cts_export_to_shrimp reference implementation)

### v1.0.0 (2025-10-30)

**Phase CTS_MCP_1 Complete** ✅

- ✅ MCP server with stdio transport
- ✅ Shrimp integration (CTS_Export_to_Shrimp tool)
- ✅ D3.js signal map renderer (force-directed graph)
- ✅ React hop dashboard renderer (interactive filtering)
- ✅ GDScript parser (signal extraction)
- ✅ Artifact caching (SHA-256 + LRU)
- ✅ 23 integration tests (100% pass rate)
- ✅ 85% functional coverage

**Metrics**:
- Total LOC: 1,097 (implementation) + 450 (tests)
- Performance: 97.7% faster than targets
- CTS Compliance: 100% (all files <500 lines)

## Roadmap

### Phase 2 (Planned)
- Dependency graph renderer (visualize hop dependencies)
- Performance chart renderer (LOC over time)
- Graph clustering (100+ signal support)
- Tree-sitter GDScript parser (robust signal extraction)

### Phase 3 (Future)
- Sandpack integration (game visualizers)
- Scene preview renderer
- Interactive mechanic demos

---

**Maintained by**: Development Team  
**Questions?**: See [MCP_PROTOCOL.md](../docs/MCP_PROTOCOL.md) or open an issue