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)

pip install contextdigger

Step 2: Install MCP Server (this package)

pip install contextdigger-mcp

Step 3: Verify installation

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:

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

If using a virtual environment:

{
  "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:

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
• Documentation
• MCP Protocol Spec
• Report Issues

---

Made with ⛏️ by the ContextDigger team