cocoindex MCP

An MCP server that incrementally indexes repositories and documents into a Postgres + pgvector store using CocoIndex, and exposes semantic search over them.

The pipeline is source → extract (format registry) → chunk → embed → store:

• Sources (src/mcp_coco/sources.py) — local filesystem today, as two profiles: repo (code-aware, vendored dirs excluded) and document (markdown/text/pdf, prose chunking).

• Formats (src/mcp_coco/formats.py) — a registry mapping a file to normalized text. PDF (via pymupdf) is just one handler; add a format by registering one.

• Indexer (src/mcp_coco/indexer.py) — the CocoIndex app: chunk + embed (sentence-transformers) and declare rows into one doc_embeddings table.

• Search (src/mcp_coco/db.py) — embeds the query and runs a pgvector similarity search.

CocoIndex tracks its incremental state in a local LMDB file (COCOINDEX_DB), so re-indexing only reprocesses what changed and removes rows for deleted files.

Prerequisites

• uv (Python package manager)

• just (task runner, optional but convenient)

• A Postgres instance with pgvector

• Docker (if you want to run pgvector via the included compose file)

Related MCP server: ragi

Quick start (local)

1. Start a pgvector database

If you already have a Postgres instance with pgvector, skip this step and set DATABASE_URL accordingly.

Otherwise, use the included compose file:

docker compose up -d

This starts pgvector on localhost:5432 with user/password/db all set to cocoindex.

2. Install dependencies

uv sync

3. Configure

cp .env.example .env

Edit .env and set DATABASE_URL to point at your Postgres instance. For the Docker-based database:

DATABASE_URL=postgresql://cocoindex:cocoindex@localhost:5432/cocoindex

Optional settings:

4. Verify the database connection

just init

5. Index something

just index ./path/to/repo repo
just index ./path/to/docs document

The first run downloads the embedding model (~80 MB) from Hugging Face.

6. Search

just search "how does authentication work"

Using with Coding Agents

Add the MCP server to your Claude Code settings (~/.claude/settings.json for global, or .claude/settings.json in a project):

{
  "mcpServers": {
    "cocoindex": {
      "command": "uv",
      "args": ["run", "--directory", "/absolute/path/to/cocoindex-mcp", "mcp-coco-server"],
      "env": {
        "DATABASE_URL": "postgresql://cocoindex:cocoindex@localhost:5432/cocoindex",
        "COCOINDEX_DB": "/absolute/path/to/cocoindex-mcp/.cocoindex/state.db"
      }
    }
  }
}

Replace /absolute/path/to/cocoindex-mcp with the actual path to this repository.

If your Postgres instance is elsewhere (e.g. a cloud-hosted database), adjust DATABASE_URL accordingly. It is highly encouraged to pass your authentication information through env vars, do NOT hardcode into the connection string!

Once configured, Claude Code can use these tools:

Two-stage search

To keep context lean, search writes full results to a temporary JSON file and returns only condensed summaries (~80-char excerpts) inline. The caller triages from the summary, then uses read_search_results to fetch full details for the results it actually needs.

By default, read_search_results re-ranks the selected results using a cross-encoder model (cross-encoder/ms-marco-MiniLM-L-6-v2) for more accurate relevance ordering. Disable with rerank=false. The model is configurable via the RERANK_MODEL environment variable.

Development (devcontainer)

1. Open this folder in VS Code and Reopen in Container (Dev Containers). The db service starts automatically alongside the app container.

2. Run the preflight check:

   just install
   just init

   Copy .env.example to .env to customize settings. Inside the devcontainer the database hostname is db (the default).

just recipes

just index <path> [repo|document|auto]   # index a path
just index-repo <path>                   # index as code repository
just index-docs <path>                   # index as document collection
just search "query" [limit]              # semantic search
just drop <path> [repo|document|auto]    # remove a source from the index
just visualize_index                     # show a map of what's indexed
just serve                               # run the MCP server over stdio
just test                                # run tests
just lint                                # run ruff