contextdigger-mcp 1.1.0
Lightweight MCP server for ContextDigger - enables AI tools to access all 50+ CLI commands
License: MIT
Requires Python: >=3.11
Keywords: ai-tools, claude-desktop, contextdigger, cursor, mcp, model-context-protocol

# ContextDigger MCP Server

Lightweight Model Context Protocol (MCP) server for ContextDigger that enables AI tools (Claude Desktop, Cursor, Windsurf, etc.) to access all 50+ ContextDigger CLI commands.

## What This Is

This package provides **only the MCP server** - a lightweight bridge between AI tools and your locally installed ContextDigger CLI.

**Architecture:**
```
AI Tool (Claude Desktop)
         ↓
    MCP Protocol
         ↓
contextdigger-mcp (this package)
         ↓
    subprocess calls
         ↓
contextdigger CLI (separate installation)
         ↓
    Your .cdg/ data
```

## Benefits

- ✅ **Lightweight**: Only ~600 lines of code, minimal dependencies
- ✅ **Separate installation**: Install/update independently from ContextDigger CLI
- ✅ **Version flexible**: Works with any version of contextdigger CLI
- ✅ **Full CLI parity**: All 50+ commands available as MCP tools
- ✅ **Easy to maintain**: No service layer duplication

## Installation

**Step 1: Install ContextDigger CLI (required)**
```bash
pip install contextdigger
```

**Step 2: Install MCP Server (this package)**
```bash
pip install contextdigger-mcp
```

**Step 3: Verify installation**
```bash
contextdigger --version        # Should show CLI version
contextdigger-mcp --help       # Should show MCP server is ready
```

## Setup for Claude Desktop

**macOS:** Edit `~/Library/Application Support/Claude/claude_desktop_config.json`

**Windows:** Edit `%APPDATA%\Claude\claude_desktop_config.json`

**Linux:** Edit `~/.config/Claude/claude_desktop_config.json`

Add this configuration:

```json
{
  "mcpServers": {
    "contextdigger": {
      "command": "contextdigger-mcp"
    }
  }
}
```

**If using a virtual environment:**
```json
{
  "mcpServers": {
    "contextdigger": {
      "command": "/path/to/venv/bin/contextdigger-mcp"
    }
  }
}
```

Restart Claude Desktop to activate.

## Available MCP Tools (50+ tools)

### Core Navigation (7 tools)
- `init_project` - Initialize ContextDigger
- `dig_area` - Focus on specific area
- `list_areas` - List all areas
- `navigate_back` - Go to previous area
- `navigate_forward` - Go to next area
- `show_history` - Show navigation history
- `show_status` - Show current session status

### Bookmarks (4 tools)
- `create_bookmark` - Save bookmark
- `goto_bookmark` - Jump to bookmark
- `list_bookmarks` - List all bookmarks
- `delete_bookmark` - Delete bookmark

### Context Snapshots (4 tools)
- `save_context` - Save context snapshot
- `load_context` - Load context snapshot
- `list_contexts` - List all snapshots
- `delete_context` - Delete snapshot

### Notes & Documentation (3 tools)
- `add_note` - Add note to area
- `show_notes` - View notes
- `generate_wiki` - Generate wiki docs

### Analysis & Intelligence (12 tools)
- `show_insights` - Generate insights
- `suggest_areas` - Get AI suggestions
- `show_dependencies` - Show dependencies
- `analyze_impact` - Impact analysis
- `show_map` - Generate codebase map
- `find_hotspots` - Find code hotspots
- `find_gaps` - Find coverage gaps
- `analyze_performance` - Performance analysis
- `run_benchmark` - Run benchmarks
- `show_trends` - Historical trend analysis (v2.2.0)
- `show_predictions` - Predictive insights (v2.2.0)
- `get_remediation` - Automated remediation (v2.2.0)

### Search & Query (2 tools)
- `search_all` - Search all areas
- `run_query` - Custom query

### Automation (2 tools)
- `show_automation` - Automation suggestions
- `list_rules` - List automation rules

### Reports & Export (8 tools)
- `show_analytics` - Work analytics
- `generate_report` - Generate report
- `export_context` - Export context
- `create_backup` - Backup .cdg/
- `show_provenance` - File provenance
- `show_dashboard` - Dashboard
- `check_health` - Health check
- `show_stats` - Statistics

### Team Features (2 tools)
- `show_team_activity` - Team activity
- `show_test_coverage` - Test coverage

### Sub-Area Management (2 tools)
- `split_area` - Split large areas
- `create_subarea` - Create sub-area

### Budget & Governance (3 tools)
- `check_budget` - Run `policy check` to verify budget compliance
- `manage_policy` - Manage policy enforcement mode (`strict`, `warning`, `advisory`)
- `show_audit` - Show audit trail

### Continuation Contracts (3 tools)
- `continue_work` - Resume work session
- `pause_work` - Pause work
- `list_contracts` - List all sessions

### LLM Integration (1 tool)
- `manage_llm` - Manage LLM integration

## Example Usage

Once configured in Claude Desktop, you can use natural language:

**User:** "Show me all focus areas in this project"
**Claude:** *Uses `list_areas` tool*

**User:** "Dig into the API area"
**Claude:** *Uses `dig_area` tool with area_id="api"*

**User:** "What insights do you have?"
**Claude:** *Uses `show_insights` tool*

**User:** "Analyze trends over time"
**Claude:** *Uses `show_trends` tool*

## Troubleshooting

### "contextdigger CLI not found"

**Solution:**
```bash
pip install contextdigger
contextdigger --version  # Verify it works
```

### MCP server not showing in Claude Desktop

1. Check JSON syntax in config file
2. Use full path to `contextdigger-mcp` if in venv
3. Completely quit and restart Claude Desktop
4. Check Claude Desktop logs (Help → Show Logs)

### Command timeout

Some commands may take longer than 60 seconds. This is a safety limit. You can:
1. Use the CLI directly for long-running commands
2. Split large areas into smaller sub-areas
3. Adjust budget limits to reduce context size

## How It Works

1. **AI tool sends MCP request** (JSON-RPC over stdin)
2. **MCP server parses request** and identifies the tool
3. **Server calls contextdigger CLI** via subprocess
4. **CLI executes command** and returns output
5. **Server formats response** and sends back to AI (via stdout)

All processing is local - no external services involved.

## Differences from Main Package

**`contextdigger` package (main):**
- Full CLI with 50+ commands
- Service layer (manager, insights, budget, etc.)
- Direct Python imports
- Faster execution
- Entry point: `contextdigger`

**`contextdigger-mcp` package (this):**
- Only MCP server
- Calls CLI via subprocess
- Lightweight (~600 lines)
- Separate installation
- Entry point: `contextdigger-mcp`

## Requirements

- **Python 3.11+**
- **ContextDigger CLI** (`pip install contextdigger`)
- **AI tool with MCP support** (Claude Desktop, Cursor, etc.)

## License

MIT License - See LICENSE file

## Links

- [ContextDigger Main Package](https://pypi.org/project/contextdigger/)
- [Documentation](https://github.com/ialameh/contextdigger#readme)
- [MCP Protocol Spec](https://spec.modelcontextprotocol.io/)
- [Report Issues](https://github.com/ialameh/contextdigger-mcp/issues)

---

**Made with ⛏️ by the ContextDigger team**