codrspot-processor-mcp

A local MCP (Model Context Protocol) client that connects Claude Code to your indexed repositories, giving it code-context retrieval and patch-generation tools for a project registered with a codrspot-processor server.

This package is the client only. It talks to a codrspot-processor server over its HTTP API; it does not include or require running the server itself.

Requirements

• Python 3.12 (3.13 is not supported)
• A reachable codrspot-processor server instance and its base URL
• A credentials.yaml manifest issued by your server operator (used to mint a JWT for each project you register)
• An OpenAI-compatible LLM endpoint (a local server or OPENAI_API_KEY for a remote provider)

No local Qdrant install is needed — the client keeps its own embedded, file-backed vector store for source chunks.

1. Install

Pick a permanent install location — this becomes CODEPREPROC_HOME. Claude Code's default expectation is %USERPROFILE%\.codepreproc on Windows, or $HOME/.codepreproc on macOS/Linux:

Windows (PowerShell)

mkdir "$env:USERPROFILE\.codepreproc"
cd "$env:USERPROFILE\.codepreproc"
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install codrspot-processor-mcp

This installs the codepreproc and codepreproc-mcp console scripts into .venv\Scripts\. To upgrade later:

python -m pip install --upgrade codrspot-processor-mcp

macOS/Linux (bash/zsh)

mkdir -p "$HOME/.codepreproc"
cd "$HOME/.codepreproc"
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install codrspot-processor-mcp

This installs the codepreproc and codepreproc-mcp console scripts into .venv/bin/. To upgrade later:

python -m pip install --upgrade codrspot-processor-mcp

Then run codepreproc setup to scaffold CODEPREPROC_HOME (indexes/, logs/, a starter .env) and print the Claude Code mcp.json snippet with the exe path already resolved. Safe to re-run — it never overwrites an existing .env.

2. Configure the environment

Create a .env file in %CODEPREPROC_HOME% ($CODEPREPROC_HOME on macOS/Linux) with at least:

CODEPREPROC_SERVER_URL=https://your-codrspot-processor-server-host:8443
OPENAI_API_KEY=sk-...            # if using a remote LLM policy

Also place the credentials.yaml your server operator gave you at %CODEPREPROC_HOME%\credentials.yaml ($CODEPREPROC_HOME/credentials.yaml on macOS/Linux), or point CODEPREPROC_CREDENTIALS at a different path.

.env is loaded automatically from %CODEPREPROC_HOME% (defaults to %USERPROFILE%\.codepreproc on Windows, $HOME/.codepreproc on macOS/Linux, if unset).

3. Register your project(s)

From inside each repo you want indexed:

Windows (PowerShell)

cd D:\path\to\your\repo
& "$env:USERPROFILE\.codepreproc\.venv\Scripts\codepreproc.exe" init

macOS/Linux (bash/zsh)

cd /path/to/your/repo
"$HOME/.codepreproc/.venv/bin/codepreproc" init

This scans the repo, mints a JWT for it from credentials.yaml, and registers it with your server over the API. Running it again on an already-registered project is a no-op.

4. Register the MCP server in Claude Code

Add this to your Claude Code MCP configuration (project .mcp.json or global settings).

Windows

{
  "mcpServers": {
    "codepreproc": {
      "command": "C:\\Users\\<username>\\.codepreproc\\.venv\\Scripts\\codepreproc-mcp.exe"
    }
  }
}

Replace <username> with your actual Windows username, and adjust the path if you installed into a folder other than %USERPROFILE%\.codepreproc.

macOS/Linux

{
  "mcpServers": {
    "codepreproc": {
      "command": "/home/<username>/.codepreproc/.venv/bin/codepreproc-mcp"
    }
  }
}

Replace <username> with your actual username (on macOS this is typically under /Users/<username>), and adjust the path if you installed into a folder other than $HOME/.codepreproc.

5. Restart Claude Code and verify

Restart Claude Code (or reload the MCP connection), then run:

• list_projects — should show the project(s) registered in step 3
• reindex with {"project": "<your-project>", "full": true} — builds the index the first time
• project_status — confirms the index is healthy and up to date

If the connection fails before it finishes initializing, check %USERPROFILE%\.codepreproc\logs\mcp_server.log ($HOME/.codepreproc/logs/mcp_server.log on macOS/Linux) — set CODEPREPROC_MCP_CONNECTION_VERBOSITY=verbose in .env for more detail.

Available tools

Once connected, Claude Code gets access to these MCP tools:

Projects and index

• list_projects — list registered projects and index status
• switch_project — set the active project for the session
• reindex — run a full or incremental reindex
• project_status — report index health and git sync state

Code changes

• analyze_request — turn a natural-language prompt into a validated patch
• preview_semantic_plan — inspect the cached edit plan for a task
• preview_patch — view the generated patch as a unified diff
• validate_patch — check a patch's structural validity
• disambiguate_region — resolve an ambiguous edit target
• apply_patch — apply a validated patch to the repo

Filesystem reorganization

• analyze_filesystem_reorg — plan file/directory moves and renames
• preview_filesystem_plan — inspect a cached reorg plan
• apply_filesystem_plan — apply a reorg plan

Search and documentation

• search_context — hybrid semantic search over the indexed repo
• generate_document — generate a Markdown document from retrieved context

Snippets

• list_snippets — list available code snippets/templates
• assemble_from_snippets — generate new code from templates for a target framework

LLM usage

• usage_report — summarize accumulated LLM cost/usage
• set_llm_policy — override the LLM routing policy for the session

Useful environment variables

• CODEPREPROC_HOME
• CODEPREPROC_SERVER_URL
• CODEPREPROC_CREDENTIALS
• CODEPREPROC_MCP_CONNECTION_VERBOSITY (off, basic, verbose)
• CODEPREPROC_DEBUG

License

See LICENSE.