Epic: MCP Integration with Adapter Framework #26

Description

Build an MCP (Model Context Protocol) server with a robust adapter framework to provide native integration with AI tools. This enables Claude Desktop, Claude Code, and Cursor to access dev-agent functionality through a standardized protocol, providing better UX than shell commands while maintaining the local-first philosophy.

MCP is Anthropic's open standard for context providers, similar to LSP (Language Server Protocol) for language features. Recently adopted by Cursor, it's becoming the de facto standard for AI tool integrations.

Key Innovation: Adapter framework allows users to extend dev-agent with custom tools without forking the codebase. Third-party adapter packages enable ecosystem growth.

Architecture

Core Components

MCP Server Core:

• JSON-RPC 2.0 protocol implementation
• Transport layer (stdio primary, HTTP future)
• Message routing and error handling
• Lifecycle management

Adapter Framework:

• Base adapter interfaces (ToolAdapter, ResourceAdapter)
• Adapter registry with discovery and lifecycle management
• Plugin architecture for user extensions
• Validation and error handling

Built-in Adapters:

• SearchAdapter: dev_search (semantic code search)
• PlanAdapter: dev_plan (GitHub issue planning)
• ExploreAdapter: dev_explore (pattern discovery, similar code, relationships)
• GitHubAdapter: dev_gh (GitHub context search and linking)
• StatusAdapter: dev_status (configuration and statistics)

Token Optimization:

• Compact formatters (reduce token usage by default)
• Configurable verbosity levels
• Response pagination and limits
• Token estimation for responses

Goals

1. ✅ Build extensible adapter framework for tools and resources
2. ✅ Implement MCP server with JSON-RPC 2.0 protocol
3. ✅ Create 5 core adapters exposing all dev-agent capabilities
4. ✅ Support Claude Desktop, Claude Code, and Cursor
5. ✅ Optimize for token efficiency (learn from Figma MCP issues)
6. ✅ Enable user custom adapters via configuration
7. ✅ Comprehensive testing and documentation

Acceptance Criteria

• MCP server implements JSON-RPC 2.0 protocol correctly
• Adapter framework allows easy creation of new adapters
• Server registers with Claude Desktop, Claude Code, and Cursor
• All core dev-agent capabilities exposed as MCP tools
• Tools return concise, structured responses (token-efficient)
• Users can add custom adapters without forking
• Integration tests with real MCP clients
• >80% test coverage for server and adapters
• Complete documentation (setup, API, adapter dev guide)

Definition of Done

• All code passes linting, formatting, and type checking
• All tests passing with >= 80% coverage
• Server tested with Claude Desktop successfully
• Server tested with Cursor successfully
• Token efficiency validated (responses < 1000 tokens typical)
• Setup guides for each supported tool
• Adapter development guide with examples
• Package published to npm as @lytics/dev-agent-mcp

Epic Breakdown

Phase 1: Foundation (MVP)

Issue #27: MCP Server Core + Adapter Framework (3 days)

• Server class with JSON-RPC 2.0
• Stdio transport implementation
• Base adapter interfaces (ToolAdapter, ResourceAdapter)
• Adapter registry with registration and execution
• Unit tests for core components
• Milestone: Framework ready for adapters! ✅

Issue #28: First Adapter + Formatters (2 days)

• SearchAdapter implementation (proves pattern works)
• CompactFormatter + VerboseFormatter
• Token estimation utilities
• Integration test with mock MCP client
• Milestone: Adapter framework validated! ✅

Phase 2: Core Adapters

Issue #29: Plan + Status Adapters (2 days)

• PlanAdapter (wrap planner subagent)
• StatusAdapter (config, stats, health)
• Unit tests for both adapters
• Integration tests

Issue #30: Explore + GitHub Adapters (2 days)

• ExploreAdapter (pattern, similar, relationships)
• GitHubAdapter (search, context, related)
• Unit tests for both adapters
• Integration tests
• Milestone: All core functionality exposed! ✅

Phase 3: Polish + Ship

Issue #31: Configuration + Discovery (1 day)

• Config file parsing (.dev-agent-mcp.json)
• Adapter auto-discovery from directory
• Enable/disable adapters via config
• Custom adapter loading
• Environment variable support

Issue #32: Documentation + Examples (2 days)

• Setup guide (Claude Desktop, Cursor, Claude Code)
• Adapter development guide with full example
• Example custom adapter (Jira integration)
• API reference documentation
• Troubleshooting guide

Issue #33: Integration Testing + Release (1 day)

• Test with real Claude Desktop
• Test with real Cursor
• Performance validation
• Token usage benchmarking
• npm package publishing
• Announcement and migration guide
• Milestone: Shipped to production! 🚀

Technical Considerations

Token Efficiency (Lessons from Figma MCP)

Problems to Avoid:

• Large tool definitions (verbose schemas)
• Large responses (full data dumps)
• Too many tools (all included in context)
• Rich formatting (human-readable but token-heavy)

Solutions:

• Compact tool definitions (concise descriptions, short parameter names)
• Default to summaries (5-10 results max, metadata only)
• Grouped tools (5 tools vs. 15)
• Lazy loading (AI can request full details if needed)
• Token estimation in responses

Adapter Framework Benefits

1. Extensibility: Users add custom tools without forking
2. Testability: Test adapters in isolation
3. Maintainability: Clear separation of concerns
4. Flexibility: Enable/disable adapters via config
5. Future-proof: Easy to add resources, prompts, new transports

Transport Strategy

v1: stdio (Standard Input/Output)

• Recommended by MCP best practices
• No port management complexity
• Process isolation for security
• Works with all MCP clients

Future: HTTP + SSE

• Long-running daemon mode
• Better for development/debugging
• Sub-second query times (warm indexes)

Security Considerations

• Input validation on all tool arguments
• Sandboxed adapter execution
• Rate limiting per tool
• Audit logging for tool calls
• Environment variable for secrets (no hardcoded credentials)

Success Metrics

• Tools discoverable in Claude Desktop/Cursor UI
• Response times < 2 seconds for most operations
• Token consumption < 50% of equivalent shell command output
• Successfully handles 10+ sequential tool calls without issues
• Positive user feedback from dogfooding
• 3rd party adapter packages created by community

Dependencies

• Epic Epic: Core Context Provider #1: Core Context Provider (completed)
• Epic Epic: Subagent Foundation #2: Subagent Foundation (completed)
• @lytics/dev-agent-core (scanner, indexer)
• @lytics/dev-agent-subagents (planner, explorer, github)
• @modelcontextprotocol/sdk (official MCP SDK if available)

Future Enhancements

• Resource adapters (static context, codebase structure)
• Prompt adapters (pre-built prompts for common tasks)
• HTTP transport (daemon mode)
• Multi-user support (workspace isolation)
• Caching layer (reduce repeated searches)
• Streaming responses (large result sets)
• VS Code extension (builds on MCP server)

Impact

For Users:

• Native AI tool integration (no copy/paste)
• Better UX than shell commands
• Discoverable tools in AI interface
• Custom adapters for team-specific needs

For Ecosystem:

• Standard integration point (MCP protocol)
• Third-party adapter packages
• Community contributions
• Enterprise extensions

For Project:

• Cleaner architecture (adapter pattern)
• Better testing (isolated components)
• Easier maintenance (modular design)
• Future-proof (easy to extend)

Priority: High (enables native AI tool integration)
Estimate: 2 weeks (13 days with overhead)
Risk: Low (incremental delivery, validate framework early)

Status: 🚀 READY TO START