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-serverready 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 detectionhop_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
- Install
bd_dev_toolsaddon (containsBDMCPClient) - Build the CTS MCP server:
npm run build - 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:
- Open Godot Editor:
godot4 --path /home/eric/Godot/ProtoBd --editor - Navigate to: Bottom Panel → GUT → Run Tests
- Select
test/cts_mcp/test_cts_mcp_client.gdin the test list - Click "Run" button
- 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 loggingSHRIMP_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:
- Ensure Shrimp MCP server is running
- Check Shrimp path configuration
- Verify stdio IPC permissions
Issue: Artifact render timeout
Cause: Large dataset (100+ signals) exceeds render budget
Solution:
- Filter signals before rendering (use
includeEventBusOnly: true) - Increase timeout in VS Code extension
- 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
- MCP Server Guide - Complete usage guide with installation, configuration, and all tool documentation
- API Reference - Comprehensive API documentation with schemas, types, and examples
- Troubleshooting Guide - Common issues and solutions
Infrastructure
- CI/CD Pipeline - GitHub Actions workflow, benchmarks, coverage
- Packaging Guide - NPM publishing and Docker deployment procedures
Technical Details
- Tier 2C Improvements - Production hardening documentation (caching, config, sampling, errors, schemas)
- Phase 2 Migration - Upgrade guide from v1.0 to v2.0
- VS Code MCP Setup - VS Code integration configuration
- WASM Setup - Tree-sitter WASM configuration
Architecture Decision Records
Project Documentation
- Test Results - Comprehensive test coverage report
- CHANGELOG - Version history and release notes
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