APM Task Assignment: Phase 2 - Enhanced MCP Features & Robustness

[IanMayo]

APM Task Assignment: Phase 2 - Enhanced MCP Features & Robustness

🔴 MANDATORY SHARED CONTEXT (All Agents Must Read)

Project State

• Tech Stack: TypeScript, VS Code Extension API, Express, WebSocket, MCP JSON-RPC 2.0
• Architecture: Monorepo with pnpm workspaces, MCP server architecture, dual-server system (Debrief + Tool Vault)
• Current Phase: Phase 2 - Enhanced Features & Robustness (1-2 weeks)
• Prerequisites: Phase 1 MCP endpoints complete and validated

Task Overview

• Problem: Need enhanced MCP tools for time/viewport management, improved error handling, and GitHub Copilot validation
• Solution: Add remaining WebSocket API commands as MCP tools with robust error handling
• Constraints:
  • Performance targets: <200ms p95 latency for get operations
  • <5s end-to-end workflows with GitHub Copilot
  • Rate limiting: 10 req/sec sustained
  • Concurrent client support: 5+ simultaneous connections

Prior Decisions (Phase 1)

• MCP JSON-RPC 2.0 implementation complete
• Dual-server architecture established (Debrief State Server + Tool Vault Server)
• WebSocket bridge on port 60123
• Basic CRUD operations for features implemented

Shared Interfaces

• MCP Tool Schema: Standard JSON-RPC 2.0 with inputSchema validation
• TimeState Interface: libs/shared-types/src/types/TimeState.ts
• ViewportState Interface: libs/shared-types/src/types/ViewportState.ts
• Error Response Format: Standard MCP error codes (-32000 to -32099)

📋 Multi-Agent Task Assignments

Phase 1: Backend MCP Tool Implementation

🤖 Agent: backend-developer (92% confidence)
🔄 Alternative: api-developer
⚙️ Model: sonnet
⏱️ Duration: 4-5 hours
🔗 Dependencies: None (can start immediately)
🚧 Blocks: Phase 2, 3, 4

Tasks:

• Implement debrief_get_time MCP tool with optional filename parameter
• Implement debrief_set_time MCP tool with TimeState validation
• Implement debrief_get_viewport MCP tool with bounds calculation
• Implement debrief_set_viewport MCP tool with ViewportState validation
• Implement debrief_list_plots utility tool for multi-plot scenarios
• Implement debrief_zoom_to_selection tool with feature bounds calculation
• Add comprehensive error handling for each tool
• Implement retry logic with exponential backoff (base delay 1000ms, max 3 retries)

Deliverables:

• Complete MCP tool implementations in apps/vs-code/src/mcp/
• Error handling utilities with isRetryableError classification
• Unit tests for all new tools

Handoff to Phase 2:

• Tool endpoint URLs and schemas
• Error codes and retry configuration
• Integration test requirements

Phase 2: TypeScript Type Safety & Contracts

🤖 Agent: typescript-developer (88% confidence)
⚙️ Model: sonnet
⏱️ Duration: 2-3 hours
🔗 Dependencies: Phase 1 completion
🚧 Blocks: Phase 3

Tasks:

• Define TypeScript interfaces for new MCP tool parameters
• Update shared-types with TimeState/ViewportState enhancements if needed
• Create type guards for runtime validation
• Add JSDoc documentation for all new interfaces
• Ensure strict type checking in tool implementations

Deliverables:

• Type definitions in libs/shared-types/src/types/
• Type guards and validators
• Updated exports in index files

Handoff to Phase 3:

• Validated type contracts
• Runtime type checking functions
• Integration points documentation

Phase 3: Error Handling & Resilience Layer

🤖 Agent: backend-developer (85% confidence)
🔄 Alternative: systems-analyst
⚙️ Model: sonnet
⏱️ Duration: 3-4 hours
🔗 Dependencies: Phase 1, 2 completion
🚧 Blocks: Phase 4, 5

Tasks:

• Implement callWithRetry utility with exponential backoff
• Create WebSocketConnectionError and ToolVaultError custom error classes
• Implement graceful degradation for Tool Vault unavailability
• Add circuit breaker pattern for failing services
• Create error recovery strategies for transient failures
• Implement detailed error logging and telemetry

Deliverables:

• Error handling utilities module
• Custom error classes with proper error codes
• Graceful degradation implementation
• Circuit breaker implementation

Handoff to Phase 4:

• Error handling patterns
• Recovery strategies documentation
• Performance impact analysis

Phase 4: Testing & Performance Validation

🤖 Agent: test-developer (90% confidence)
⚙️ Model: sonnet
⏱️ Duration: 4-5 hours
🔗 Dependencies: Phase 1, 2, 3 completion
🚧 Blocks: Phase 5

Tasks:

• Create unit tests for all new MCP tools (100% coverage target)
• Implement performance benchmark suite (p95 latency tests)
• Create stress testing scenarios (rate limiting, concurrent connections)
• Test retry logic and exponential backoff
• Validate graceful degradation scenarios
• Create end-to-end workflow tests
• Memory leak detection tests for long-running sessions

Deliverables:

• Complete test suite in apps/vs-code/test/
• Performance benchmark results
• Stress test reports
• Memory profile analysis

Handoff to Phase 5:

• Test results and metrics
• Performance bottlenecks identified
• Optimization recommendations

Phase 5: GitHub Copilot Integration Validation

🤖 Agent: frontend-developer (82% confidence)
🔄 Alternative: systems-analyst
⚙️ Model: sonnet
⏱️ Duration: 3-4 hours
🔗 Dependencies: All previous phases
🚧 Blocks: Phase 6

Tasks:

• Validate MCP servers auto-start with VS Code workspace
• Test GitHub Copilot can list all Debrief tools
• Verify multi-step workflows (get → process → update)
• Validate error messages display in chat panel
• Confirm real-time map updates
• Test multiple concurrent operations
• Verify performance (<5s end-to-end workflows)
• Document GitHub Copilot usage patterns

Test Scenarios:

• Delete selected feature workflow
• Filter features by criteria workflow
• Update selection programmatically workflow
• Multi-plot workflows with filename specification
• Error handling scenarios (service unavailable, invalid params)

Deliverables:

• GitHub Copilot integration test results
• Usage documentation for LLM interactions
• Performance validation report

Phase 6: Documentation & Release

🤖 Agent: code-documenter (95% confidence)
⚙️ Model: sonnet
⏱️ Duration: 2-3 hours
🔗 Dependencies: All previous phases
🚧 Blocks: None

Tasks:

• Update API documentation for all new MCP tools
• Create GitHub Copilot integration guide
• Document error handling patterns and recovery strategies
• Update performance benchmarks documentation
• Create troubleshooting guide for common issues
• Update CHANGELOG.md with Phase 2 features
• Create release notes

Deliverables:

• Complete API documentation
• Integration guides
• Release notes and changelog
• Troubleshooting documentation

🔄 Context Management Protocol

Before Starting:

1. Read entire shared context and Phase 1 implementation
2. Review existing MCP tool implementations in apps/vs-code/src/mcp/
3. Check .claude/task-context/phase-2-mcp/ for any prior work
4. Familiarize with WebSocket API in apps/vs-code/src/websocket/

During Task:

1. Update context.yaml with architectural decisions
2. Document new error codes and their meanings
3. Note performance metrics and bottlenecks
4. Create integration test scenarios
5. Log any API contract changes

After Completing:

1. Create detailed handoff document for next agent
2. Update shared context with implementation details
3. Commit all test results and performance metrics
4. Update status in project tracking

✅ Success Criteria

Functional Requirements

• ✅ All WebSocket API commands available as MCP tools
• ✅ Time state management (get/set) fully functional
• ✅ Viewport management (get/set/zoom) operational
• ✅ Plot listing and multi-plot support working
• ✅ Zoom to selection feature implemented

Performance Requirements

• ✅ <200ms p95 latency for get operations
• ✅ <5s p95 for end-to-end workflows
• ✅ 10 req/sec sustained rate limit handling
• ✅ 5+ concurrent client support validated
• ✅ No memory leaks in 1-hour sessions

Integration Requirements

• ✅ GitHub Copilot can discover all tools
• ✅ Error messages display clearly in VS Code
• ✅ Real-time map updates functional
• ✅ Multi-step workflows execute reliably

Quality Requirements

• ✅ 90%+ test coverage for new code
• ✅ Zero regressions in existing functionality
• ✅ All error scenarios handled gracefully
• ✅ Complete API documentation

🎯 Memory Bank Requirements

For Implementation Team:

• Log all architectural decisions with rationale
• Document error code mappings and meanings
• Record performance optimization techniques used
• Note any GitHub Copilot-specific workarounds
• Track dependencies between MCP tools

For QA Team:

• Document test scenarios and edge cases
• Record performance baseline metrics
• Note any flaky tests and mitigation
• Log stress test configurations

📊 Risk Assessment

Technical Risks

• WebSocket connection stability: Mitigated by retry logic and circuit breaker
• Performance degradation with concurrent clients: Addressed by connection pooling
• Tool Vault service unavailability: Handled by graceful degradation
• GitHub Copilot compatibility: Validated through comprehensive integration tests

Schedule Risks

• Integration complexity: Mitigated by clear phase dependencies
• Performance optimization time: Buffer built into timeline
• External service dependencies: Fallback strategies implemented

🚀 Implementation Notes

Priority Order:

1. Time and viewport tools (core functionality)
2. Error handling layer (critical for robustness)
3. Performance optimization (user experience)
4. GitHub Copilot validation (integration requirement)

Dependencies:

• Requires Phase 1 MCP implementation complete
• WebSocket bridge must be operational
• Shared types package must be up-to-date

Testing Strategy:

• Unit tests first (isolated tool testing)
• Integration tests second (multi-tool workflows)
• Performance tests third (load and stress)
• GitHub Copilot validation last (end-user experience)

---

Labels: enhancement, phase-2, performance, TAP, multi-agent

Milestone: Phase 2 - Enhanced Features & Robustness

Assignees: To be assigned based on agent availability

Time Estimate: 1-2 weeks (parallel agent execution reduces timeline)