Metadata-Version: 2.4
Name: codrspot-processor-mcp
Version: 0.1.3
Summary: Local MCP server exposing codepreproc's code-context tools to Claude Code
Author-email: alexlqi <alexlqi@gmail.com>
License: Copyright (c) 2026 alexlqi (alexlqi@gmail.com)
        
        All rights reserved.
        
        Redistribution and use of this software, in source or binary form, with or
        without accompanying documentation, is permitted provided that:
        
        1. The software is redistributed unmodified and in its entirety (as-is),
           retaining this license and all copyright notices.
        2. No person or entity may distribute, publish, sublicense, or otherwise
           make available to any third party, in whole or in part, any modified
           version or derivative work of this software (including but not limited
           to versions that have been altered, decompiled, reverse-engineered, or
           otherwise changed in functionality), without prior written consent from
           the copyright holder. This restriction applies to distribution only;
           it does not prohibit creating modifications for private, non-distributed
           use.
        3. This license text is included, unaltered, with every copy or substantial
           portion of the software that is redistributed.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
        FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
        IN THE SOFTWARE.
        
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: Microsoft :: Windows
Classifier: License :: Other/Proprietary License
Requires-Python: <3.13,>=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: anyio
Requires-Dist: python-dotenv
Requires-Dist: bm25s
Requires-Dist: filelock
Requires-Dist: gitpython
Requires-Dist: httpx
Requires-Dist: mcp
Requires-Dist: numpy
Requires-Dist: openai
Requires-Dist: pydantic>=2
Requires-Dist: pyyaml
Requires-Dist: qdrant-client[fastembed]>=1.10.0
Requires-Dist: sentence-transformers
Requires-Dist: torch
Requires-Dist: tree-sitter
Requires-Dist: tree-sitter-languages
Requires-Dist: watchdog
Requires-Dist: xxhash
Requires-Dist: pyahocorasick
Requires-Dist: zstandard
Dynamic: license-file

# 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)**

```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:

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

**macOS/Linux (bash/zsh)**

```bash
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:

```bash
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:

```dotenv
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)**

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

**macOS/Linux (bash/zsh)**

```bash
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**

```json
{
  "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**

```json
{
  "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](LICENSE).
