Skip to main content
Glama
EricA1019

CTS MCP Server

by EricA1019
OverviewSchemaRelated ServersScoreDiscussions
Hybrid

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

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):

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:

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

Output:

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

Example:

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:

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:

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:

{
  "projectPath": "/home/user/Godot/MyProject",
  "renderMap": true
}

Output:

{
  "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: Comprehensive API documentation for all tools, artifact types, and renderer APIs

  • πŸš€ Deployment Guide: Production deployment strategies (systemd, PM2, Docker)

  • πŸ§ͺ Integration Examples: Full code examples for signal scanning, artifact rendering, export

Quick Start

Installation

cd cts_mcp
npm install
npm run build

Verify Installation:

npm test
# Expected: 868+ tests passing

Enable Production Renderers

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:

{
  "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:

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

Examples

Example 1: Render Signal Map

# 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

# 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)

# 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

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:

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:

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:

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

Example:

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:

# 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

# 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:

# 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:

# 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:

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

npm run build          # Compile TypeScript β†’ JavaScript
npm run dev            # Development mode (no build)

Testing

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

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:

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:

npm install          # Ensure dependencies installed
npm run build        # Check for specific errors

Documentation

Guides

Infrastructure

Technical Details

Architecture Decision Records

Project Documentation

Contributing

See CONTRIBUTING.md for development guidelines.

License

MIT License - See 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 or open an issue

This server cannot be installed

-
security - not tested
F
license - not found
-
quality - not tested

How are these scores calculated?

Resources

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/EricA1019/CTS_MCP'

If you have feedback or need assistance with the MCP directory API, please join our Discord server