Codebase Contextifier

You run a local MCP server that indexes codebases, builds a semantic search index, and tracks relationships between functions and their dependencies. It operates entirely on your machine, using on‑disk storage and local models, so your code stays under your control while you search across multiple repositories with fast, AST‑aware indexing and graph queries.

How to use

You use an MCP client to connect to the server, index repositories, search across indexed code, and explore relationships between symbols. Start an on‑demand indexer for a repository, monitor progress, run semantic searches, and query the relationship graph to understand code flow and dependencies. You can index multiple projects with a shared backend, enable real‑time updates, and leverage local embeddings for fast results.

How to install

Prerequisites: install Docker Desktop (or Docker with Docker Compose) and ensure Ollama is available locally for embeddings.

Option A: Centralized Server (recommended) — index from the MCP server and query across all repositories.

# 1. Start the backend
cd codebase-contextifier-9000
docker-compose up -d

# 2. Configure Claude Desktop (see below)

# 3. Index any repository
# In Claude: "Index the repository at /Users/me/projects/my-app"

Centralized server CLI/config example

{
  "mcpServers": {
    "codebase-contextifier": {
      "command": "docker",
      "args": [
        "exec",
        "-i",
        "codebase-mcp-server",
        "python",
        "-m",
        "src.server"
      ]
    }
  }
}

Per‑project setup

Option B: Each project manages its own indexing.

# 1. Start shared backend (once)
cd codebase-contextifier-9000
docker-compose up -d

# 2. Copy .mcp.json to each project
cp .mcp.json.template ~/projects/my-app/.mcp.json

# 3. Open project in Claude Code
cd ~/projects/my-app
claude-code .

Claude Desktop configuration

For Centralized Server (Option A) you configure Claude Desktop to connect to the MCP server container.

{
  "mcpServers": {
    "codebase-contextifier": {
      "command": "docker",
      "args": [
        "exec",
        "-i",
        "codebase-mcp-server",
        "python",
        "-m",
        "src.server"
      ]
    }
  }
}

Usage with the MCP client

Index a repository, monitor progress, search across repositories, and explore symbol usages and dependencies using natural language queries. The MCP server spawns indexers as needed, updates a shared vector store and graph, and returns progress and results through the client.

Configuration and environment

Configure the environment to control paths, models, and services. The following variables are used to tailor the server behavior.

Troubleshooting

If you encounter health or connectivity issues, verify the required services are running, check container logs, and ensure paths and credentials are correctly set.

Development

To run locally without Docker, install dependencies, set environment variables, and start the local services. See the detailed steps below for the exact commands.

Available tools

index_repository

Spawns an indexer container to index a repository from a host path, enabling incremental indexing and parallel work flows.

get_job_status

Returns the status and progress of an ongoing indexing job, including per-file progress and cache hit rates.

list_indexing_jobs

Lists all indexing jobs, including completed, running, and queued tasks, with their progress summaries.

cancel_indexing_job

Cancels a running indexing job and reports the outcome to the user.

search_code

Performs semantic search across all indexed repositories with optional filters for language, repository, and file path.

get_symbols

Extracts symbols from a file using AST parsing to return function and class definitions with location data.

find_usages

Finds all usages of a symbol across the codebase using the graph database relationships.

find_dependencies

Finds dependencies and relationships that a symbol relies on within the codebase graph.

query_graph

Executes custom Cypher queries against the Neo4j graph database for advanced analysis.

detect_dependencies

Detects available external dependencies such as WordPress plugins, Composer packages, and npm modules.

index_dependencies

Indexes external dependencies into the knowledge base to improve understanding of external APIs.

list_indexed_dependencies

Lists all dependencies that have been indexed in the knowledge base.