Skip to main content
Glama

Codebase MCP Server

by Ravenight13
GitHub
Python
  • Apple
  • Linux
OverviewInspectNewEndpointsSchemaRelated ServersReviewsScore
Need Help?View Source CodeReport Issue

Codebase MCP Server

A production-grade MCP (Model Context Protocol) server that indexes code repositories into PostgreSQL with pgvector for semantic search, designed specifically for AI coding assistants.

Overview

The Codebase MCP Server provides semantic code search capabilities through a focused, local-first architecture. It enables AI assistants to understand and navigate codebases efficiently by combining tree-sitter AST parsing with vector embeddings.

Key Features

  • Semantic Code Search: Natural language queries across indexed repositories

  • Repository Indexing: Fast scanning and chunking with tree-sitter parsers

  • Task Management: Development task tracking with git integration

  • MCP Protocol: Six focused tools via Server-Sent Events (SSE) and stdio (JSON-RPC)

  • Performance Guaranteed: 60-second indexing for 10K files, 500ms p95 search latency

  • Production Ready: Comprehensive error handling, structured logging, type safety

MCP Tools

  1. search_code: Semantic search across indexed code

  2. index_repository: Index a repository for searching

  3. get_task: Retrieve a specific development task

  4. list_tasks: List tasks with filtering options

  5. create_task: Create a new development task

  6. update_task: Update task status with git integration

Quick Start

1. Database Setup

# Create database createdb codebase_mcp # Initialize schema psql -d codebase_mcp -f db/init_tables.sql

2. Install Dependencies

# Install dependencies including FastMCP framework uv sync # Or with pip pip install -r requirements.txt

Key Dependencies:

  • fastmcp>=0.1.0 - Modern MCP framework with decorator-based tools

  • anthropic-mcp - MCP protocol implementation

  • sqlalchemy>=2.0 - Async ORM

  • pgvector - PostgreSQL vector extension

  • ollama - Embedding generation

3. Configure Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{ "mcpServers": { "codebase-mcp": { "command": "uv", "args": [ "run", "--with", "fastmcp", "python", "/absolute/path/to/codebase-mcp/server_fastmcp.py" ] } } }

Important:

  • Use absolute paths!

  • Server uses FastMCP framework with decorator-based tool definitions

  • All logs go to /tmp/codebase-mcp.log (no stdout/stderr pollution)

4. Start Ollama

ollama serve ollama pull nomic-embed-text

5. Test

# Test database and tools uv run python tests/test_tool_handlers.py # Test repository indexing uv run python tests/test_embeddings.py

Current Status

Working Tools (6/6) ✅

Tool

Status

Description

create_task

✅ Working

Create development tasks with planning references

get_task

✅ Working

Retrieve task by ID

list_tasks

✅ Working

List tasks with filters (status, branch)

update_task

✅ Working

Update tasks with git tracking (branch, commit)

index_repository

✅ Working

Index code repositories with semantic chunking

search_code

✅ Working

Semantic code search with pgvector similarity

Recent Fixes (Oct 6, 2025)

  • ✅ Parameter passing architecture (Pydantic models)

  • ✅ MCP schema mismatches (status enums, missing parameters)

  • ✅ Timezone/datetime compatibility (PostgreSQL)

  • ✅ Binary file filtering (images, cache dirs)

Test Results

✅ Task Management: 7/7 tests passed ✅ Repository Indexing: 2 files indexed, 6 chunks created ✅ Embeddings: 100% coverage (768-dim vectors) ✅ Database: Connection pooling, async operations working

Tool Usage Examples

Create a Task

In Claude Desktop:

Create a task called "Implement user authentication" with description "Add JWT-based authentication to the API"

Response:

{ "id": "550e8400-e29b-41d4-a716-446655440000", "title": "Implement user authentication", "description": "Add JWT-based authentication to the API", "status": "need to be done", "created_at": "2025-10-06T21:30:00", "planning_references": [] }

Index a Repository

Index the repository at /Users/username/projects/myapp

Response:

{ "repository_id": "abc123...", "files_indexed": 234, "chunks_created": 1456, "duration_seconds": 12.5, "status": "success" }

Search Code

Search for "authentication middleware" in Python files

Response:

{ "results": [ { "file_path": "src/middleware/auth.py", "content": "def authenticate_request(request):\n ...", "start_line": 45, "similarity_score": 0.92 } ], "total_count": 5, "latency_ms": 250 }

Track Task with Git

Update task abc123 to status "in-progress" and link it to branch "feature/auth"

Response:

{ "id": "abc123...", "status": "in-progress", "branches": ["feature/auth"], "commits": [] }

Architecture

Claude Desktop ↔ FastMCP Server ↔ Tool Handlers ↔ Services ↔ PostgreSQL ↓ Ollama (embeddings)

MCP Framework: Built with FastMCP - a modern, decorator-based framework for building MCP servers with:

  • Type-safe tool definitions via @mcp.tool() decorators

  • Automatic JSON Schema generation from Pydantic models

  • Dual logging (file + MCP protocol) without stdout pollution

  • Async/await support throughout

See ARCHITECTURE.md for detailed component diagrams.

Documentation

Database Schema

11 tables with pgvector for semantic search:

Core Tables:

  • repositories - Indexed repositories

  • code_files - Source files with metadata

  • code_chunks - Semantic chunks with embeddings (vector(768))

  • tasks - Development tasks with git tracking

  • task_status_history - Audit trail

See docs/ARCHITECTURE.md for complete schema documentation.

Technology Stack

  • MCP Framework: FastMCP 0.1+ (decorator-based tool definitions)

  • Server: Python 3.13+, FastAPI patterns, async/await

  • Database: PostgreSQL 14+ with pgvector extension

  • Embeddings: Ollama (nomic-embed-text, 768 dimensions)

  • ORM: SQLAlchemy 2.0 (async), Pydantic V2 for validation

  • Type Safety: Full mypy --strict compliance

Development

Running Tests

# Tool handlers uv run python tests/test_tool_handlers.py # Repository indexing uv run python tests/test_embeddings.py # Unit tests uv run pytest tests/ -v

Code Structure

codebase-mcp/ ├── server_fastmcp.py # FastMCP server entry point (NEW) ├── src/ │ ├── mcp/ │ │ └── tools/ # Tool handlers with service integration │ │ ├── tasks.py # Task management │ │ ├── indexing.py # Repository indexing │ │ └── search.py # Semantic search │ ├── services/ # Business logic layer │ │ ├── tasks.py # Task CRUD + git tracking │ │ ├── indexer.py # Indexing orchestration │ │ ├── scanner.py # File discovery │ │ ├── chunker.py # AST-based chunking │ │ ├── embedder.py # Ollama integration │ │ └── searcher.py # pgvector similarity search │ └── models/ # Database models + Pydantic schemas │ ├── task.py # Task, TaskCreate, TaskUpdate │ ├── code_chunk.py # CodeChunk │ └── ... └── tests/ ├── test_tool_handlers.py # Integration tests └── test_embeddings.py # Embedding validation

FastMCP Server Architecture:

  • server_fastmcp.py - Main entry point using @mcp.tool() decorators

  • Tool handlers in src/mcp/tools/ provide service integration

  • Services in src/services/ contain all business logic

  • Dual logging: file (/tmp/codebase-mcp.log) + MCP protocol

Prerequisites

System Requirements

  • Python 3.11+ (3.13 compatible)

  • PostgreSQL 14+ with pgvector extension

  • Ollama for embedding generation

  • 4GB+ RAM recommended

  • SSD storage for optimal performance

PostgreSQL with pgvector

# Install PostgreSQL 14+ # macOS brew install postgresql@14 brew services start postgresql@14 # Ubuntu/Debian sudo apt-get update sudo apt-get install postgresql-14 postgresql-contrib-14 # Install pgvector extension # macOS brew install pgvector # Ubuntu/Debian sudo apt install postgresql-14-pgvector # Enable pgvector in your database psql -U postgres -c "CREATE EXTENSION IF NOT EXISTS vector;"

Ollama Setup

# Install Ollama # macOS brew install ollama # Linux curl -fsSL https://ollama.com/install.sh | sh # Start Ollama service ollama serve # Pull required embedding model ollama pull nomic-embed-text

Installation

1. Clone the Repository

git clone https://github.com/cliffclarke/codebase-mcp.git cd codebase-mcp

2. Create Virtual Environment

# Create virtual environment python3.11 -m venv .venv # Activate virtual environment # macOS/Linux source .venv/bin/activate # Windows .venv\Scripts\activate

3. Install Dependencies

# Install production dependencies (includes FastMCP) pip install -r requirements.txt # For development (includes testing and linting tools) pip install -r requirements-dev.txt # Or with uv (recommended) uv sync

Key Dependencies Installed:

  • fastmcp>=0.1.0 - Modern MCP framework

  • sqlalchemy>=2.0 - Async database ORM

  • pgvector - PostgreSQL vector extension Python bindings

  • ollama - Embedding generation client

  • pydantic>=2.0 - Data validation and settings

4. Configure Environment

# Copy example environment file cp .env.example .env # Edit .env with your configuration nano .env

Environment Variables:

# Database Configuration DATABASE_URL=postgresql+asyncpg://user:password@localhost:5432/codebase_mcp # Ollama Configuration OLLAMA_BASE_URL=http://localhost:11434 OLLAMA_EMBEDDING_MODEL=embeddinggemma # Performance Tuning EMBEDDING_BATCH_SIZE=50 # Batch size for embedding generation MAX_CONCURRENT_REQUESTS=10 # Max parallel Ollama requests # Logging LOG_LEVEL=INFO # DEBUG, INFO, WARNING, ERROR LOG_FILE=/tmp/codebase-mcp.log # Log file location

Database Setup

1. Create Database

# Connect to PostgreSQL psql -U postgres # Create database CREATE DATABASE codebase_mcp; # Enable pgvector extension \c codebase_mcp CREATE EXTENSION IF NOT EXISTS vector; \q

2. Initialize Schema

# Run database initialization script python scripts/init_db.py # Verify schema creation alembic current

The initialization script will:

  • Create all required tables (repositories, files, chunks, tasks)

  • Set up vector indexes for similarity search

  • Configure connection pooling

  • Apply all database migrations

3. Verify Setup

# Check database connectivity python -c "from src.database import Database; import asyncio; asyncio.run(Database.create_pool())" # Run migration status check alembic current

4. Database Reset & Cleanup

During development, you may need to reset your database. See DATABASE_RESET.md for three reset options:

  • scripts/clear_data.sh - Clear all data, keep schema (fastest, no restart needed)

  • scripts/reset_database.sh - Drop and recreate all tables (recommended for schema changes)

  • scripts/nuclear_reset.sh - Drop entire database (requires Claude Desktop restart)

# Quick data wipe (keeps schema) ./scripts/clear_data.sh # Full table reset (recommended) ./scripts/reset_database.sh # Nuclear option (drops database) ./scripts/nuclear_reset.sh

Running the Server

FastMCP Server (Recommended)

The primary way to run the server is via Claude Desktop or other MCP clients:

# Via Claude Desktop (configured in claude_desktop_config.json) # Server starts automatically when Claude Desktop launches # Manual testing with FastMCP CLI uv run --with fastmcp python server_fastmcp.py # With custom log level LOG_LEVEL=DEBUG uv run --with fastmcp python server_fastmcp.py

Server Entry Point: server_fastmcp.py in repository root

Logging: All output goes to /tmp/codebase-mcp.log (configurable via LOG_FILE env var)

Development Mode (Legacy FastAPI)

# Start with auto-reload (if FastAPI server exists) uvicorn src.main:app --reload --host 127.0.0.1 --port 3000 # With custom log level LOG_LEVEL=DEBUG uvicorn src.main:app --reload

Production Mode (Legacy)

# Start production server uvicorn src.main:app --host 0.0.0.0 --port 3000 --workers 4 # With gunicorn (recommended for production) gunicorn src.main:app -w 4 -k uvicorn.workers.UvicornWorker --bind 0.0.0.0:3000

stdio Transport (Legacy CLI Mode)

The legacy MCP server supports stdio transport for CLI clients via JSON-RPC 2.0 over stdin/stdout.

# Start stdio server (reads JSON-RPC from stdin) python -m src.mcp.stdio_server # Echo a single request echo '{"jsonrpc":"2.0","id":1,"method":"list_tasks","params":{"limit":5}}' | python -m src.mcp.stdio_server # Pipe requests from a file (one JSON-RPC request per line) cat requests.jsonl | python -m src.mcp.stdio_server # Interactive mode (type JSON-RPC requests manually) python -m src.mcp.stdio_server {"jsonrpc":"2.0","id":1,"method":"get_task","params":{"task_id":"..."}}

JSON-RPC 2.0 Request Format:

{ "jsonrpc": "2.0", "id": 1, "method": "search_code", "params": { "query": "async def", "limit": 10 } }

JSON-RPC 2.0 Response Format:

{ "jsonrpc": "2.0", "id": 1, "result": { "results": [...], "total_count": 42, "latency_ms": 250 } }

Available Methods:

  • search_code - Semantic code search

  • index_repository - Index a repository

  • get_task - Get task by ID

  • list_tasks - List tasks with filters

  • create_task - Create new task

  • update_task - Update task status

Logging: All logs go to /tmp/codebase-mcp.log (configurable via LOG_FILE env var). No stdout/stderr pollution - only JSON-RPC protocol messages on stdout.

Health Check

# Check server health curl http://localhost:3000/health # Expected response: { "status": "healthy", "database": "connected", "ollama": "connected", "version": "0.1.0" }

Usage Examples

1. Index a Repository

# Via MCP protocol { "tool": "index_repository", "arguments": { "path": "/path/to/your/repo", "name": "My Project", "force_reindex": false } } # Response { "repository_id": "uuid-here", "files_indexed": 150, "chunks_created": 1200, "duration_seconds": 45.3, "status": "success" }

2. Search Code

# Search for authentication logic { "tool": "search_code", "arguments": { "query": "user authentication password validation", "limit": 10, "file_type": "py" } } # Response includes ranked code chunks with context { "results": [...], "total_count": 25, "latency_ms": 230 }

3. Task Management

# Create a task { "tool": "create_task", "arguments": { "title": "Implement rate limiting", "description": "Add rate limiting to API endpoints", "planning_references": ["specs/rate-limiting.md"] } } # Update task with git integration { "tool": "update_task", "arguments": { "task_id": "task-uuid", "status": "complete", "branch": "feature/rate-limiting", "commit": "abc123..." } }

Architecture

┌─────────────────────────────────────────────────┐ │ MCP Client (AI) │ └─────────────────┬───────────────────────────────┘ │ SSE Protocol ┌─────────────────▼───────────────────────────────┐ │ MCP Server Layer │ │ ┌──────────────────────────────────────────┐ │ │ │ Tool Registration & Routing │ │ │ └──────────────────────────────────────────┘ │ │ ┌──────────────────────────────────────────┐ │ │ │ Request/Response Handling │ │ │ └──────────────────────────────────────────┘ │ └─────────────────┬───────────────────────────────┘ │ ┌─────────────────▼───────────────────────────────┐ │ Service Layer │ │ ┌────────────┐ ┌────────────┐ ┌────────────┐ │ │ │ Indexer │ │ Searcher │ │Task Manager│ │ │ └──────┬─────┘ └──────┬─────┘ └──────┬─────┘ │ │ │ │ │ │ │ ┌──────▼──────────────▼──────────────▼──────┐ │ │ │ Repository Service │ │ │ └──────┬─────────────────────────────────────┘ │ │ │ │ │ ┌──────▼─────────────────────────────────────┐ │ │ │ Embedding Service (Ollama) │ │ │ └─────────────────────────────────────────────┘│ └─────────────────┬───────────────────────────────┘ │ ┌─────────────────▼───────────────────────────────┐ │ Data Layer │ │ ┌──────────────────────────────────────────┐ │ │ │ PostgreSQL with pgvector │ │ │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │ │ │ │Repository│ │ Files │ │ Chunks │ │ │ │ │ └──────────┘ └──────────┘ └──────────┘ │ │ │ │ ┌──────────┐ ┌──────────────────────┐ │ │ │ │ │ Tasks │ │ Vector Embeddings │ │ │ │ │ └──────────┘ └──────────────────────┘ │ │ │ └──────────────────────────────────────────┘ │ └──────────────────────────────────────────────────┘

Component Overview

  • MCP Layer: Handles protocol compliance, tool registration, SSE transport

  • Service Layer: Business logic for indexing, searching, task management

  • Repository Service: File system operations, git integration, .gitignore handling

  • Embedding Service: Ollama integration for generating text embeddings

  • Data Layer: PostgreSQL with pgvector for storage and similarity search

Data Flow

  1. Indexing: Repository → Parse → Chunk → Embed → Store

  2. Searching: Query → Embed → Vector Search → Rank → Return

  3. Task Tracking: Create → Update → Git Integration → Query

Testing

Run All Tests

# Run all tests with coverage pytest tests/ -v --cov=src --cov-report=term-missing # Run specific test categories pytest tests/unit/ -v # Unit tests only pytest tests/integration/ -v # Integration tests pytest tests/contract/ -v # Contract tests

Test Categories

  • Unit Tests: Fast, isolated component tests

  • Integration Tests: Database and service integration

  • Contract Tests: MCP protocol compliance validation

  • Performance Tests: Latency and throughput benchmarks

Coverage Requirements

  • Minimum coverage: 95%

  • Critical paths: 100%

  • View HTML report: open htmlcov/index.html

Performance Tuning

Database Optimization

-- Optimize vector searches CREATE INDEX ON chunks USING ivfflat (embedding vector_cosine_ops) WITH (lists = 100); -- Adjust work_mem for large result sets ALTER SYSTEM SET work_mem = '256MB'; SELECT pg_reload_conf();

Connection Pool Settings

# In .env DATABASE_POOL_SIZE=20 # Connection pool size DATABASE_MAX_OVERFLOW=10 # Max overflow connections DATABASE_POOL_TIMEOUT=30 # Connection timeout in seconds

Embedding Batch Size

# Adjust based on available memory EMBEDDING_BATCH_SIZE=100 # For systems with 8GB+ RAM EMBEDDING_BATCH_SIZE=50 # Default for 4GB RAM EMBEDDING_BATCH_SIZE=25 # For constrained environments

Troubleshooting

Common Issues

  1. Database Connection Failed

    • Check PostgreSQL is running: pg_ctl status

    • Verify DATABASE_URL in .env

    • Ensure database exists: psql -U postgres -l

  2. Ollama Connection Error

    • Check Ollama is running: curl http://localhost:11434/api/tags

    • Verify model is installed: ollama list

    • Check OLLAMA_BASE_URL in .env

  3. Slow Performance

    • Check database indexes: \di in psql

    • Monitor query performance: See logs at LOG_FILE path

    • Adjust batch sizes and connection pool

For detailed troubleshooting, see docs/troubleshooting.md and docs/guides/SETUP_GUIDE.md.

Contributing

We follow a specification-driven development workflow using the Specify framework.

Development Workflow

  1. Feature Specification: Use /specify command to create feature specs

  2. Planning: Generate implementation plan with /plan

  3. Task Breakdown: Create tasks with /tasks

  4. Implementation: Execute tasks with /implement

Git Workflow

# Create feature branch git checkout -b 001-feature-name # Make atomic commits git add . git commit -m "feat(component): add specific feature" # Push and create PR git push origin 001-feature-name

Code Quality Standards

  • Type Safety: mypy --strict must pass

  • Linting: ruff check with no errors

  • Testing: All tests must pass with 95%+ coverage

  • Documentation: Update relevant docs with changes

Constitutional Principles

  1. Simplicity Over Features: Focus on core semantic search

  2. Local-First Architecture: No cloud dependencies

  3. Protocol Compliance: Strict MCP adherence

  4. Performance Guarantees: Meet stated benchmarks

  5. Production Quality: Comprehensive error handling

See .specify/memory/constitution.md for full principles.

FastMCP Migration (Oct 2025)

Migration Complete: The server has been successfully migrated from the legacy MCP SDK to the modern FastMCP framework.

What Changed

Before (MCP SDK):

# Old: Manual tool registration with JSON schemas class MCPServer: def __init__(self): self.tools = { "search_code": { "name": "search_code", "description": "...", "inputSchema": {...} } }

After (FastMCP):

# New: Decorator-based tool definitions @mcp.tool() async def search_code(query: str, limit: int = 10) -> dict[str, Any]: """Semantic code search with natural language queries.""" # Implementation

Key Benefits

  1. Simpler Tool Definitions: Decorators replace manual JSON schema creation

  2. Type Safety: Automatic schema generation from Pydantic models

  3. Dual Logging: File logging + MCP protocol without stdout pollution

  4. Better Error Handling: Structured error responses with context

  5. Cleaner Architecture: Separation of tool interface from business logic

Server Files

  • New Entry Point: server_fastmcp.py (root directory)

  • Legacy Server: src/mcp/mcp_stdio_server_v3.py (deprecated, will be removed)

  • Tool Handlers: src/mcp/tools/*.py (unchanged, reused by FastMCP)

  • Services: src/services/*.py (unchanged, business logic intact)

Configuration Update Required

Update your Claude Desktop config to use the new server:

{ "mcpServers": { "codebase-mcp": { "command": "uv", "args": ["run", "--with", "fastmcp", "python", "/path/to/server_fastmcp.py"] } } }

Migration Notes

  • All 6 MCP tools remain functional (100% backward compatible)

  • No database schema changes required

  • Tool signatures and responses unchanged

  • Logging now goes exclusively to /tmp/codebase-mcp.log

  • All tests pass with FastMCP implementation

Performance

FastMCP maintains performance targets:

  • Repository indexing: <60 seconds for 10K files

  • Code search: <500ms p95 latency

  • Async/await throughout for optimal concurrency

License

MIT License - see LICENSE file for details.

Support

Acknowledgments

  • MCP framework powered by FastMCP

  • Built with FastAPI, SQLAlchemy, and Pydantic

  • Vector search powered by pgvector

  • Embeddings via Ollama and nomic-embed-text

  • Code parsing with tree-sitter

  • MCP protocol by Anthropic

This server cannot be installed

-
security - not tested
-
license - not tested
-
quality - not tested

How are these scores calculated?

hybrid server

The server is able to function both locally and remotely, depending on the configuration or use case.

Enables AI assistants to semantically search and understand code repositories using PostgreSQL with pgvector embeddings. Provides repository indexing, natural language code search, and development task management with git integration.

  1. Overview
    1. Key Features
    2. MCP Tools
  2. Quick Start
    1. 1. Database Setup
    2. 2. Install Dependencies
    3. 3. Configure Claude Desktop
    4. 4. Start Ollama
    5. 5. Test
  3. Current Status
    1. Working Tools (6/6) ✅
    2. Recent Fixes (Oct 6, 2025)
    3. Test Results
  4. Tool Usage Examples
    1. Create a Task
    2. Index a Repository
    3. Search Code
    4. Track Task with Git
  5. Architecture
    1. Documentation
      1. Database Schema
        1. Technology Stack
          1. Development
            1. Running Tests
            2. Code Structure
          2. Prerequisites
            1. System Requirements
            2. PostgreSQL with pgvector
            3. Ollama Setup
          3. Installation
            1. 1. Clone the Repository
            2. 2. Create Virtual Environment
            3. 3. Install Dependencies
            4. 4. Configure Environment
          4. Database Setup
            1. 1. Create Database
            2. 2. Initialize Schema
            3. 3. Verify Setup
            4. 4. Database Reset & Cleanup
          5. Running the Server
            1. FastMCP Server (Recommended)
            2. Development Mode (Legacy FastAPI)
            3. Production Mode (Legacy)
            4. stdio Transport (Legacy CLI Mode)
            5. Health Check
          6. Usage Examples
            1. 1. Index a Repository
            2. 2. Search Code
            3. 3. Task Management
          7. Architecture
            1. Component Overview
            2. Data Flow
          8. Testing
            1. Run All Tests
            2. Test Categories
            3. Coverage Requirements
          9. Performance Tuning
            1. Database Optimization
            2. Connection Pool Settings
            3. Embedding Batch Size
          10. Troubleshooting
            1. Common Issues
          11. Contributing
            1. Development Workflow
            2. Git Workflow
            3. Code Quality Standards
            4. Constitutional Principles
          12. FastMCP Migration (Oct 2025)
            1. What Changed
            2. Key Benefits
            3. Server Files
            4. Configuration Update Required
            5. Migration Notes
            6. Performance
          13. License
            1. Support
              1. Acknowledgments

                New MCP Servers

                MCP directory API

                We provide all the information about MCP servers via our MCP API.

                curl -X GET 'https://glama.ai/api/mcp/v1/servers/Ravenight13/codebase-mcp'

                If you have feedback or need assistance with the MCP directory API, please join our Discord server