techdebtgpt · amar-zhuri · Jan 30, 2026
diff --git a/.gitignore b/.gitignore
@@ -6,13 +6,22 @@ dist/
 
 # Evaluation results
 .evaluated-commits/
+
+# Test temp files
+.test-temp/
 results.json
 report.html
 index.html
 
 # Claude Code configuration
 .claude/
 
+#Cursor
+.Cursor
+
+#Tests
+coverage
+
 # IDE configuration
 .vscode/*
 !.vscode/extensions.json

diff --git a/README.md b/README.md
@@ -1062,6 +1062,152 @@ codewave evaluate --commit HEAD
 
 ---
 
+## MCP Integration with Claude Desktop
+
+CodeWave is available as an **MCP (Model Context Protocol) server**, allowing you to evaluate commits and analyze code quality directly within **Claude Desktop** through natural conversation.
+
+### What You Can Do
+
+- **Evaluate commits conversationally**: Ask Claude to evaluate your latest commits
+- **Get insights without commands**: No need to remember CLI syntax
+- **Generate OKRs**: Create data-driven development goals based on commit history
+- **Compare quality**: Track improvements between commits
+- **Analyze teams**: Get team-wide code quality statistics
+- **Export reports**: Save evaluations to HTML/Markdown/JSON formats
+
+### Quick Start
+
+```bash
+# 1. Install CodeWave globally
+npm install -g @techdebtgpt/codewave
+
+# 2. Configure CodeWave
+codewave config --init
+
+# 3. Setup Claude Desktop
+# See docs/MCP_SETUP.md for detailed instructions
+```
+
+### Example Conversation
+
+```
+You: "Evaluate my last commit and tell me if there are any concerns"
+
+Claude: [Uses CodeWave MCP to evaluate]
+        "I've evaluated commit abc123. Overall score: 8.5/10.
+
+        The code quality is excellent (9.0/10), but there are two concerns:
+        1. Missing rate limiting on the login endpoint
+        2. Password validation could be stronger
+
+        I recommend adding rate limiting before pushing to production..."
+```
+
+### Available Tools
+
+- **10 production-ready tools** for evaluation, analytics, and reporting
+- **Support for inline configuration** (no config file needed)
+- **Three analysis modes**: fast, normal, and deep
+- **Batch operations**: Evaluate up to 10 commits at once
+- **No API calls** for analytics tools (instant results)
+
+### Key Features
+
+| Feature | Description |
+|---------|-------------|
+| Natural language interface | Chat with Claude instead of remembering commands |
+| Conversational workflows | Combine multiple tools in one conversation |
+| Context awareness | Claude remembers previous results in the conversation |
+| Intelligent interpretation | Claude explains results in plain language |
+| Follow-up questions | Ask for clarification or deeper analysis |
+
+### Available MCP Tools
+
+| Tool | Purpose | Makes API Calls? |
+|------|---------|------------------|
+| `evaluate_commit` | Evaluate single commit | Yes |
+| `batch_evaluate` | Evaluate multiple commits | Yes |
+| `generate_okr` | Generate developer OKRs | Yes |
+| `check_config` | Verify configuration | No |
+| `list_evaluations` | Browse evaluation history | No |
+| `get_report` | Get detailed commit report | No |
+| `get_author_stats` | Analyze developer stats | No |
+| `compare_commits` | Compare two commits | No |
+| `get_team_stats` | Team-wide statistics | No |
+| `export_report` | Export to file | No |
+
+### Documentation
+
+- **[MCP Setup Guide](./docs/MCP_SETUP.md)** - Installation and Claude Desktop configuration
+- **[MCP Tools Reference](./docs/MCP_TOOLS_REFERENCE.md)** - Complete tool documentation with examples
+- **[MCP Examples](./docs/MCP_EXAMPLES.md)** - Practical workflows and example conversations
+
+### Requirements
+
+- **Claude Desktop** app installed ([download](https://claude.ai/download))
+- **Node.js** ≥18.0.0
+- **CodeWave** globally installed
+- **Valid configuration** with LLM API key
+
+### How It Works
+
+```
+┌─────────────────┐
+│  Claude Desktop │
+│   (Your Chat)   │
+└────────┬────────┘
+         │
+         │ Natural language request
+         │ "Evaluate my last commit"
+         │
+         ▼
+┌─────────────────┐
+│  MCP Protocol   │
+│   (JSON-RPC)    │
+└────────┬────────┘
+         │
+         │ Tool call: evaluate_commit
+         │
+         ▼
+┌─────────────────┐
+│ CodeWave Server │
+│  Multi-Agent AI │
+└────────┬────────┘
+         │
+         │ Results
+         │
+         ▼
+┌─────────────────┐
+│  Claude Desktop │
+│ (Interprets &   │
+│  Explains)      │
+└─────────────────┘
+```
+
+### Getting Started
+
+1. **Complete setup**: Follow the [MCP Setup Guide](./docs/MCP_SETUP.md)
+2. **Try examples**: See [MCP Examples](./docs/MCP_EXAMPLES.md) for workflows
+3. **Learn tools**: Reference [MCP Tools Reference](./docs/MCP_TOOLS_REFERENCE.md) as needed
+
+### MCP vs CLI
+
+Both interfaces use the same CodeWave engine. Choose based on your workflow:
+
+| Use Case | Recommended Interface |
+|----------|----------------------|
+| Interactive exploration | **MCP (Claude Desktop)** |
+| Quick quality checks | **MCP (Claude Desktop)** |
+| Learning patterns | **MCP (Claude Desktop)** |
+| Performance reviews | **MCP (Claude Desktop)** |
+| CI/CD automation | **CLI** |
+| Scripting/batch jobs | **CLI** |
+| Custom integrations | **CLI + API** |
+
+See [docs/MCP_SETUP.md](./docs/MCP_SETUP.md) for complete setup instructions.
+
+---
+
 ## Examples
 
 ### Example 1: Evaluate Latest 5 Commits

diff --git a/cli/mcp-server.ts b/cli/mcp-server.ts
@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+
+/**
+ * CLI Entry Point for CodeWave MCP Server
+ *
+ * Usage:
+ *   npx codewave-mcp
+ *   node dist/cli/mcp-server.js
+ */
+
+import { startServer } from '../src/mcp-server/index';
+
+// Start the MCP server
+startServer().catch((error) => {
+  console.error('Failed to start CodeWave MCP server:', error);
+  process.exit(1);
+});
diff --git a/docs/CONFIGURATION.md b/docs/CONFIGURATION.md
@@ -777,6 +777,133 @@ cp ~/.codewave/config.json.backup ~/.codewave/config.json
 
 ---
 
+## MCP Configuration
+
+When using CodeWave as an MCP server with Claude Desktop or Cursor, the configuration works the same way as the CLI.
+
+### Configuration Methods
+
+**1. File-based configuration (recommended):**
+
+- Use `.codewave.config.json` in your repository root or home directory
+- Run `codewave config --init` to create interactively
+- MCP server will automatically detect and use this file
+- Same configuration file used by both CLI and MCP
+
+**2. Inline configuration:**
+
+- Pass `provider`, `api_key`, and `model` directly in MCP tool calls
+- Useful when no config file exists or for testing different providers
+- All three parameters are required together
+- Example (in Claude Desktop conversation):
+
+```
+"Evaluate HEAD with Google Gemini"
+[Claude will prompt for api_key if needed]
+```
+
+Or you can provide all inline parameters:
+
+```json
+{
+  "commit_hash": "HEAD",
+  "provider": "google",
+  "api_key": "your-google-api-key",
+  "model": "gemini-2.0-flash-exp"
+}
+```
+
+### Verifying Configuration
+
+Use the `check_config` MCP tool to verify your configuration:
+
+**In Claude Desktop:**
+```
+"Check my CodeWave configuration"
+```
+
+This will return:
+- **Provider**: anthropic, openai, google, etc.
+- **Model**: claude-3-5-sonnet-20241022, gpt-4, etc.
+- **API Key Status**: Present (✓) or Missing (✗) - never shows actual key
+- **Enabled Agents**: BA, DA, DR, SA, QA
+- **Configuration Path**: Where the config file is located
+
+### API Key Security
+
+**Important security notes:**
+
+1. **Never commit** `.codewave.config.json` to version control
+   ```bash
+   echo ".codewave.config.json" >> .gitignore
+   ```
+
+2. **API keys are not logged**: Only the last 4 characters are shown in logs for debugging
+
+3. **Inline keys are not stored**: Keys passed inline in MCP calls are used once and discarded
+
+4. **Claude Desktop isolation**: Your API keys never leave your machine - MCP runs locally
+
+### Configuration Priority
+
+When both file and inline config are provided:
+
+1. **Inline parameters** (provider/api_key/model) take highest priority
+2. **File configuration** used if no inline params provided
+3. **Error** if neither is available
+
+**Example scenarios:**
+
+| Scenario | File Config | Inline Config | Result |
+|----------|-------------|---------------|--------|
+| Both present | ✓ Anthropic | ✓ Google | Uses **Google** (inline wins) |
+| Only file | ✓ Anthropic | ✗ None | Uses **Anthropic** |
+| Only inline | ✗ None | ✓ Google | Uses **Google** |
+| Neither | ✗ None | ✗ None | **Error** - run config --init |
+
+### Claude Desktop Setup
+
+For complete Claude Desktop setup instructions, see:
+- **[MCP_SETUP.md](./MCP_SETUP.md)** - Installation and configuration guide
+- **[MCP_TOOLS_REFERENCE.md](./MCP_TOOLS_REFERENCE.md)** - Tool documentation
+
+### Example: Using Different Providers
+
+You can easily test different LLM providers without changing your config file:
+
+**With file config (Anthropic):**
+```
+"Evaluate my last commit"
+[Uses Claude from config file]
+```
+
+**Override with Google inline:**
+```
+"Evaluate HEAD using Google Gemini with my API key"
+[Claude will use inline Google config]
+```
+
+**Back to file config:**
+```
+"Evaluate HEAD~1"
+[Uses Claude from config file again]
+```
+
+### Environment Variables
+
+MCP server also supports environment variables for API keys:
+
+```bash
+# Set in shell before starting Claude Desktop
+export ANTHROPIC_API_KEY="your-anthropic-key"
+export OPENAI_API_KEY="your-openai-key"
+export GOOGLE_API_KEY="your-google-key"
+```
+
+Priority: **Inline > Config File > Environment Variables**
+
+---
+
 ## Troubleshooting
 
 ### "API Key not found"