README.mdโข30.7 kB
# 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