Skip to content

Commit 3610c75

Browse files
matteiusmatteius
committed
Add MCP instructions
1 parent a6f9ec4 commit 3610c75

File tree

1 file changed

+150
-17
lines changed

1 file changed

+150
-17
lines changed

‎README.md‎

Lines changed: 150 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,7 @@ A next-generation code comparison tool that performs structural and semantic ana
1515
- **Command Line Interface**: Comprehensive CLI with multiple output formats
1616
- **Web Interface**: Modern React-based UI with interactive visualizations
1717
- **REST API**: Full-featured API for programmatic integration
18+
- **MCP Server**: Model Context Protocol server for AI agent integration
1819

1920
### Visualization Modes
2021
- **Side-by-Side View**: Synchronized code comparison with change highlighting
@@ -151,28 +152,153 @@ curl -X POST http://localhost:3000/api/compare \
151152
}'
152153
```
153154

155+
## 🤖 MCP Server for AI Agents
156+
157+
Smart Diff provides a Model Context Protocol (MCP) server that allows AI agents like Claude to perform intelligent code comparisons.
158+
159+
### Quick Setup for Claude Desktop
160+
161+
1. **Build the MCP server:**
162+
```bash
163+
cargo build --release -p smart-diff-mcp-server
164+
```
165+
166+
2. **Configure Claude Desktop:**
167+
168+
Edit your Claude Desktop config file:
169+
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
170+
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
171+
- **Linux**: `~/.config/Claude/claude_desktop_config.json`
172+
173+
Add the smart-diff server:
174+
```json
175+
{
176+
"mcpServers": {
177+
"smart-diff": {
178+
"command": "/absolute/path/to/codediff/target/release/smart-diff-mcp",
179+
"args": [],
180+
"env": {
181+
"RUST_LOG": "info"
182+
}
183+
}
184+
}
185+
}
186+
```
187+
188+
3. **Restart Claude Desktop** and verify the tools are available.
189+
190+
### Quick Setup for Augment Code (VS Code)
191+
192+
For Augment Code, we recommend using the SSE (Server-Sent Events) bridge to avoid timeout issues with large comparisons:
193+
194+
1. **Install Python dependencies:**
195+
```bash
196+
cd crates/mcp-server
197+
pip install aiohttp
198+
# or with pipenv:
199+
pipenv install aiohttp
200+
```
201+
202+
2. **Start the SSE bridge:**
203+
```bash
204+
cd crates/mcp-server
205+
./start_sse_bridge.sh
206+
# or manually:
207+
python3 sse_bridge.py --binary ../../target/release/smart-diff-mcp --port 8011
208+
```
209+
210+
3. **Configure Augment:**
211+
212+
Edit: `~/.config/Code/User/globalStorage/augment.vscode-augment/augment-global-state/mcpServers.json`
213+
214+
Add or update the smart-diff entry:
215+
```json
216+
{
217+
"type": "sse",
218+
"name": "smart-diff",
219+
"url": "http://127.0.0.1:8011/sse",
220+
"id": "your-unique-id-here",
221+
"tools": [],
222+
"disabled": false
223+
}
224+
```
225+
226+
4. **Restart VS Code** or toggle the server in Augment's MCP settings.
227+
228+
### Available MCP Tools
229+
230+
The MCP server provides four main tools:
231+
232+
- **`compare_locations`**: Compare two code locations (files or directories)
233+
- **`list_changed_functions`**: List functions sorted by change magnitude
234+
- **`get_function_diff`**: Get detailed diff for a specific function
235+
- **`get_comparison_summary`**: Get summary statistics for a comparison
236+
237+
### Example Usage with AI Agents
238+
239+
Once configured, you can ask your AI agent:
240+
241+
```
242+
Compare /old/src with /new/src and show me the top 5 most changed functions
243+
```
244+
245+
```
246+
Analyze the code changes between these directories and identify any refactoring patterns
247+
```
248+
249+
```
250+
Compare these two versions and explain what changed in the authentication logic
251+
```
252+
253+
For detailed MCP setup instructions, see:
254+
- [MCP Server README](crates/mcp-server/README.md)
255+
- [Claude Desktop Setup](crates/mcp-server/CLAUDE_SETUP.md)
256+
- [Augment SSE Bridge Setup](crates/mcp-server/SSE_SETUP.md)
257+
258+
### Troubleshooting MCP Setup
259+
260+
**Server not appearing in Claude/Augment:**
261+
- Verify the binary path is absolute and correct
262+
- Check file permissions: `chmod +x target/release/smart-diff-mcp`
263+
- Review logs in the AI client's log directory
264+
265+
**SSE Bridge issues (Augment):**
266+
- Check if bridge is running: `curl http://127.0.0.1:8011/health`
267+
- Verify Python dependencies: `pip install aiohttp`
268+
- Check port availability (default: 8011)
269+
- View bridge logs in the terminal where it's running
270+
271+
**Comparison timeouts:**
272+
- For large codebases, use the SSE bridge instead of stdio
273+
- Increase timeout settings in your AI client if available
274+
- Consider comparing smaller directory subsets
275+
154276
## 🏗️ Architecture
155277

156278
Smart Code Diff follows a modular architecture with clear separation of concerns:
157279

158280
```
159-
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
160-
│ Web UI │ │ CLI │ │ REST API │
161-
│ (React/TS) │ │ (Rust) │ │ (Axum) │
162-
└─────────────────┘ └─────────────────┘ └─────────────────┘
163-
│ │ │
164-
└───────────────────────┼───────────────────────┘
165-
│
166-
┌───────────────────────────────────────────────┐
167-
│ Core Engine │
168-
└───────────────────────────────────────────────┘
169-
│
170-
┌────────────┬────────────────┼────────────────┬────────────┐
171-
│ │ │ │ │
172-
┌───▼───┐ ┌───▼───┐ ┌───▼───┐ ┌───▼───┐ ┌───▼───┐
173-
│Parser │ │Semantic│ │ Diff │ │Function│ │Change │
174-
│Engine │ │Analysis│ │Engine │ │Matcher │ │Classifier│
175-
└───────┘ └───────┘ └───────┘ └───────┘ └───────┘
281+
┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
282+
│ Web UI │ │ CLI │ │ REST API │ │ MCP Server │
283+
│ (React/TS) │ │ (Rust) │ │ (Axum) │ │ (Rust) │
284+
└─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘
285+
│ │ │ │
286+
└────────────────┼─────────────────┼────────────────┘
287+
│ │
288+
│ ┌────────────┘
289+
│ │
290+
┌──────────────────────────────────────────────┐
291+
│ Core Engine │
292+
│ • Smart Matcher • Change Classifier │
293+
│ • Refactoring Detector • Impact Analyzer │
294+
└──────────────────────────────────────────────┘
295+
│
296+
┌───────────┬───────┼───────┬───────────┬──────────┐
297+
│ │ │ │ │ │
298+
┌───▼───┐ ┌───▼───┐ ┌─▼──┐ ┌──▼────┐ ┌───▼────┐ ┌───▼────┐
299+
│Parser │ │Semantic│ │Diff│ │Function│ │Change │ │Refactor│
300+
│Engine │ │Analysis│ │Algo│ │Matcher │ │Classify│ │Detector│
301+
└───────┘ └───────┘ └────┘ └────────┘ └────────┘ └────────┘
176302
```
177303

178304
### Core Components
@@ -297,6 +423,13 @@ duplicate_threshold = 0.85
297423
- **[Configuration Reference](docs/configuration.md)**: Detailed configuration options
298424
- **[Examples](examples/)**: Practical usage examples and tutorials
299425

426+
### MCP Server Documentation
427+
428+
- **[MCP Server README](crates/mcp-server/README.md)**: Overview and features
429+
- **[Claude Desktop Setup](crates/mcp-server/CLAUDE_SETUP.md)**: Step-by-step Claude configuration
430+
- **[Augment SSE Bridge Setup](crates/mcp-server/SSE_SETUP.md)**: Python bridge for Augment Code
431+
- **[MCP Usage Guide](crates/mcp-server/MCP_USAGE.md)**: Detailed tool documentation
432+
300433
## 🤝 Contributing
301434

302435
We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details. Note: all contributors must sign our CLA (handled via CLA Assistant on GitHub). See [CLA.md](CLA.md) for the terms you agree to when contributing.

0 commit comments

Comments
 (0)