feat: add MCP server implementation

[amar-zhuri]

feat: Add MCP (Model Context Protocol) Server Integration

Summary

This PR adds a complete MCP server implementation for CodeWave, enabling users to evaluate commits and analyze code quality directly within Claude Desktop or Cursor through natural conversation. This eliminates the need to remember CLI commands and provides an intuitive conversational interface for commit evaluation.

What's New

Core Implementation

• MCP Server (src/mcp-server/): Full Model Context Protocol server implementation
  • Tool registry system for managing 10 production-ready tools
  • Handler system for routing tool calls to appropriate functions
  • Context management for project paths and configuration
  • Comprehensive error handling and logging

Available Tools (10 total)

1. evaluate_commit - Evaluate single commit with multi-agent analysis
2. batch_evaluate - Evaluate multiple commits (up to 10 at once)
3. generate_okr - Generate developer OKRs based on commit history
4. check_config - Verify CodeWave configuration
5. list_evaluations - Browse evaluation history
6. get_report - Get detailed commit evaluation report
7. get_author_stats - Analyze developer statistics
8. compare_commits - Compare metrics between two commits
9. get_team_stats - Team-wide code quality statistics
10. export_report - Export reports to HTML/Markdown/JSON

CLI Entry Point

• New cli/mcp-server.ts entry point for running the MCP server
• Integrated into npm package binaries

Key Features

• Natural Language Interface: Chat with Claude or Cursor instead of remembering commands
• Conversational Workflows: Combine multiple tools in one conversation
• Context Awareness: Claude or Cursor remembers previous results in the conversation
• Intelligent Interpretation: Claude or Cursor explains results in plain language
• No API Calls for Analytics: Instant results for stats/listing tools (no LLM calls)
• Inline Configuration Support: Can pass config directly without config files
• Three Analysis Modes: fast, normal, and deep depth modes supported

Documentation

Complete documentation added:

• MCP_SETUP.md: Step-by-step setup guide for Claude Desktop integration
• MCP_TOOLS_REFERENCE.md: Complete tool documentation with examples
• MCP_EXAMPLES.md: Practical workflows and example conversations
• README.md: Updated with MCP integration section
• CONFIGURATION.md: Updated with MCP configuration details
• QUICK_REFERENCE.md: Updated with MCP quick reference

Configuration Updates

• Updated .gitignore to exclude MCP-related build artifacts
• Updated package.json with MCP server dependencies
• Added vitest.config.ts for test configuration

How It Works

Users can now ask Claude:

• "Evaluate my last commit"
• "Show me my code quality trends"
• "Generate OKRs for my team"
• "Compare commit abc123 with def456"

Benefits

• Better UX: Natural conversation instead of CLI commands
• Faster Insights: Claude interprets results and explains them
• Follow-up Questions: Ask for clarification or deeper analysis
• Workflow Integration: Use CodeWave without leaving Claude Desktop

Breaking Changes

None. This is a purely additive feature. Existing CLI functionality remains unchanged.

Testing Instructions

1. Install CodeWave globally: npm install -g @techdebtgpt/codewave
2. Configure CodeWave: codewave config --init
3. Setup Claude Desktop: Follow docs/MCP_SETUP.md
4. Test in Claude Desktop: "Check my CodeWave configuration"

Related Documentation

• MCP Setup Guide
• MCP Tools Reference
• MCP Examples

Checklist

• MCP server implementation complete
• All 10 tools implemented and tested
• Documentation complete
• CLI entry point added
• Error handling and logging
• TypeScript types defined
• No breaking changes to existing CLI