Codebase MCP Server

# Codebase MCP Server **Status:** ✅ Production-ready **Last Updated:** October 6, 2025 Semantic code search and task management via MCP protocol for Claude Desktop. --- ## Quick Start ```bash # 1. Prerequisites check psql -U cliffclarke -d codebase_mcp -c "SELECT 1" # Database OK? curl http://localhost:11434/api/tags # Ollama OK? # 2. Run tests cd /Users/cliffclarke/Claude_Code/codebase-mcp source .venv/bin/activate ./quick_start.sh # 3. Configure Claude Desktop # Copy claude_desktop_config.json to: # ~/Library/Application Support/Claude/claude_desktop_config.json # 4. Restart Claude Desktop killall Claude # 5. Verify in Claude Desktop # Look for 🔨 tools menu → "codebase-mcp" → 6 tools ``` --- ## Documentation | File | Purpose | When to Read | |------|---------|-------------| | **EXECUTIVE_SUMMARY.md** | TL;DR of the fix | Start here | | **MCP_STDIO_FIX.md** | Detailed troubleshooting | Issues with setup | | **WRONG_VS_RIGHT.md** | Side-by-side code comparison | Learning/debugging | | **claude_desktop_config.json** | Sample configuration | Setup phase | | **quick_start.sh** | One-command test script | Testing | --- ## Architecture ``` Claude Desktop (MCP client) ↓ stdio transport mcp_stdio_server.py (MCP server using official SDK) ↓ Tool Handlers (search, index, tasks) ↓ Services (chunker, embedder, searcher) ↓ Database (PostgreSQL + pgvector) Ollama (embedding generation) ``` --- ## Available Tools 1. **search_code** - Semantic code search across indexed repos 2. **index_repository** - Index a git repository for search 3. **list_tasks** - List tasks with optional filtering 4. **get_task** - Get task details by ID 5. **create_task** - Create a new task 6. **update_task** - Update existing task --- ## What Was Fixed **Problem:** Original `stdio_server.py` was a custom JSON-RPC server that didn't speak MCP protocol. **Solution:** New `mcp_stdio_server.py` uses official MCP SDK for protocol compliance. **Key Changes:** - ✅ Protocol compliance (initialize, tools/list, tools/call) - ✅ Proper database session management - ✅ Tool discovery and registration - ✅ Parameter validation via schemas See **WRONG_VS_RIGHT.md** for detailed comparison. --- ## File Structure ``` codebase-mcp/ ├── src/ │ ├── mcp/ │ │ ├── mcp_stdio_server.py ✅ USE THIS │ │ ├── stdio_server.py ❌ DEPRECATED │ │ ├── tools/ ✅ Tool handlers (working) │ │ └── logging.py ✅ Structured logging │ ├── services/ ✅ Core services │ ├── models/ ✅ Database models │ └── database.py ✅ Connection management ├── tests/ │ └── test_mcp_server.py ✅ Test suite ├── EXECUTIVE_SUMMARY.md 📖 Start here ├── MCP_STDIO_FIX.md 📖 Troubleshooting ├── WRONG_VS_RIGHT.md 📖 Learning guide ├── claude_desktop_config.json ⚙️ Sample config └── quick_start.sh 🚀 Test script ``` --- ## Troubleshooting ### "Module not found" → Add `cwd` to Claude Desktop config ### "Database connection failed" ```bash psql -U cliffclarke -d codebase_mcp -c "SELECT 1" ``` ### "Ollama not responding" ```bash curl http://localhost:11434/api/tags ollama list | grep embeddinggemma ``` ### "No tools visible in Claude Desktop" 1. Check logs: `tail -f /tmp/codebase-mcp.log` 2. Restart Claude Desktop: `killall Claude` 3. Verify config location: `~/Library/Application Support/Claude/` --- ## Tech Stack - **Python 3.13** - Modern async/await - **FastAPI** - SSE transport (for testing) - **PostgreSQL 18 + pgvector** - Vector similarity search - **SQLAlchemy + asyncpg** - Async database ORM - **Ollama** - Local embedding generation - **Tree-sitter** - AST-based code parsing - **MCP SDK** - Protocol implementation --- ## Development ### Running Tests ```bash python tests/test_mcp_server.py ``` ### Adding New Tools 1. Create tool handler in `src/mcp/tools/` 2. Register in `mcp_stdio_server.py`: - Add to `list_tools()` - Add to `call_tool()` dispatcher 3. Add input schema 4. Test with test suite ### Database Migrations ```bash # Generate migration alembic revision --autogenerate -m "description" # Apply migration alembic upgrade head ``` --- ## Production Deployment **Requirements:** - PostgreSQL 18+ with pgvector extension - Ollama with embeddinggemma:latest model - Python 3.11+ with all requirements.txt installed - Write access to log file location **Environment Variables:** ```bash DATABASE_URL=postgresql+asyncpg://user:pass@host:5432/db OLLAMA_BASE_URL=http://localhost:11434 OLLAMA_EMBEDDING_MODEL=embeddinggemma:latest LOG_LEVEL=INFO LOG_FILE=/var/log/codebase-mcp.log ``` --- ## Support **Check logs first:** ```bash tail -f /tmp/codebase-mcp.log ``` **Run diagnostics:** ```bash python tests/test_mcp_server.py ``` **Read documentation:** - Problems during setup → MCP_STDIO_FIX.md - Understanding the architecture → WRONG_VS_RIGHT.md - Quick answers → EXECUTIVE_SUMMARY.md --- ## License MIT License - See LICENSE file --- ## Contributing 1. Read WRONG_VS_RIGHT.md to understand the architecture 2. Run tests before and after changes 3. Follow existing code style (mypy --strict compliance) 4. Update documentation for new features --- **Status:** ✅ Ready for production use **Confidence:** 95% **Next action:** Run `./quick_start.sh` Make it so. 🖖