codrspot-processor-mcp 0.1.2__tar.gz → 0.1.3__tar.gz

{codrspot_processor_mcp-0.1.2 → codrspot_processor_mcp-0.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codrspot-processor-mcp
-Version: 0.1.2
+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)

{codrspot_processor_mcp-0.1.2 → codrspot_processor_mcp-0.1.3}/README.md

@@ -1,205 +1,205 @@
-# 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).
+# 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).

{codrspot_processor_mcp-0.1.2 → codrspot_processor_mcp-0.1.3}/pyproject.toml

@@ -1,52 +1,52 @@
-[build-system]
-requires = ["setuptools>=69", "wheel"]
-build-backend = "setuptools.build_meta"
-
-[project]
-name = "codrspot-processor-mcp"
-version = "0.1.2"
-description = "Local MCP server exposing codepreproc's code-context tools to Claude Code"
-readme = "README.md"
-requires-python = ">=3.12,<3.13"
-license = { file = "LICENSE" }
-authors = [
-  { name = "alexlqi", email = "alexlqi@gmail.com" },
-]
-classifiers = [
-  "Programming Language :: Python :: 3.12",
-  "Operating System :: Microsoft :: Windows",
-  "License :: Other/Proprietary License",
-]
-dependencies = [
-  "anyio",
-  "python-dotenv",
-  "bm25s",
-  "filelock",
-  "gitpython",
-  "httpx",
-  "mcp",
-  "numpy",
-  "openai",
-  "pydantic>=2",
-  "pyyaml",
-  "qdrant-client[fastembed]>=1.10.0",
-  "sentence-transformers",
-  "torch",
-  "tree-sitter",
-  "tree-sitter-languages",
-  "watchdog",
-  "xxhash",
-  "pyahocorasick",
-  "zstandard",
-]
-
-[project.scripts]
-codepreproc-mcp = "codepreproc_client.layer1_business.mcp.server:run"
-codepreproc = "codepreproc_client.layer1_business.cli.main:run"
-
-[tool.setuptools]
-package-dir = {"" = "src"}
-
-[tool.setuptools.packages.find]
-where = ["src"]
-include = ["codepreproc_client*", "contracts*"]
+[build-system]
+requires = ["setuptools>=69", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "codrspot-processor-mcp"
+version = "0.1.3"
+description = "Local MCP server exposing codepreproc's code-context tools to Claude Code"
+readme = "README.md"
+requires-python = ">=3.12,<3.13"
+license = { file = "LICENSE" }
+authors = [
+  { name = "alexlqi", email = "alexlqi@gmail.com" },
+]
+classifiers = [
+  "Programming Language :: Python :: 3.12",
+  "Operating System :: Microsoft :: Windows",
+  "License :: Other/Proprietary License",
+]
+dependencies = [
+  "anyio",
+  "python-dotenv",
+  "bm25s",
+  "filelock",
+  "gitpython",
+  "httpx",
+  "mcp",
+  "numpy",
+  "openai",
+  "pydantic>=2",
+  "pyyaml",
+  "qdrant-client[fastembed]>=1.10.0",
+  "sentence-transformers",
+  "torch",
+  "tree-sitter",
+  "tree-sitter-languages",
+  "watchdog",
+  "xxhash",
+  "pyahocorasick",
+  "zstandard",
+]
+
+[project.scripts]
+codepreproc-mcp = "codepreproc_client.layer1_business.mcp.server:run"
+codepreproc = "codepreproc_client.layer1_business.cli.main:run"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["codepreproc_client*", "contracts*"]

{codrspot_processor_mcp-0.1.2 → codrspot_processor_mcp-0.1.3}/src/codepreproc_client/layer1_business/api_client/reasoning_client.py

@@ -9,12 +9,15 @@ this module only builds requests and validates typed responses.
 
 from __future__ import annotations
 
+import logging
 from collections.abc import Awaitable, Callable
 from typing import Any
 
 import httpx
 from pydantic import BaseModel
 
+_logger = logging.getLogger(__name__)
+
 from contracts.dtos import (
     ROUTING_MATRIX,
     IntentSpec,
@@ -100,10 +103,32 @@ class LLMRuntime:
 
     def __init__(self, base_url: str, jwt_provider: Callable[[], Awaitable[str]]) -> None:
         self.router = LLMRouter(base_url, jwt_provider)
+        self._base_url = base_url
+        self._jwt_provider = jwt_provider
 
     async def close(self) -> None:
         pass  # no local provider connections to release
 
+    async def usage_report(self, *, project: str | None, since_days: int) -> dict[str, object]:
+        """Cost/usage accounting lives entirely server-side (CostTracker); this
+        calls the GET /usage_report proxy instead of a local cost_tracker
+        attribute, which the client never has."""
+        jwt = await self._jwt_provider()
+        params: dict[str, Any] = {"since_days": since_days}
+        if project:
+            params["project"] = project
+        try:
+            async with httpx.AsyncClient(base_url=self._base_url, timeout=DEFAULT_TIMEOUT_S) as client:
+                response = await client.get(
+                    "/v1/usage_report",
+                    params=params,
+                    headers={"Authorization": f"Bearer {jwt}"},
+                )
+                response.raise_for_status()
+        except httpx.HTTPError as exc:
+            raise ProviderUnavailableError(str(exc)) from exc
+        return response.json()
+
 
 class IntentExtractor:
     """Extract structured intent from a user prompt (ported from the server's
@@ -147,8 +172,12 @@ class IntentExtractor:
                 task_id=task_id,
             )
             return IntentSpec.model_validate(result) if not isinstance(result, IntentSpec) else result, usage
-        except Exception:
-            return IntentSpec(change_summary=user_prompt, constraints=[]), LLMUsageStats(provider="fallback", task_type="intent_extraction")
+        except Exception as exc:
+            _logger.warning("intent extraction failed, falling back to raw prompt: %s", exc)
+            return (
+                IntentSpec(change_summary=user_prompt, constraints=[]),
+                LLMUsageStats(provider="fallback", task_type="intent_extraction", fallback_from=f"{type(exc).__name__}: {exc}"),
+            )
 
 
 __all__ = [

{codrspot_processor_mcp-0.1.2 → codrspot_processor_mcp-0.1.3}/src/codepreproc_client/layer1_business/api_client/superkg_client.py

@@ -74,6 +74,11 @@ class SuperKGClient:
         self._jwt_provider = jwt_provider
         self._timeout = timeout
         self._enrich_timeout = enrich_timeout
+        # Reason the most recent _post() call returned None, so callers that
+        # care about *why* registration/bootstrap failed (e.g. _ensure_superkg_system)
+        # can surface something more actionable than a bare None. All the
+        # fire-and-forget callers below can keep ignoring this.
+        self.last_error: str | None = None
 
     # ------------------------------------------------------------------
     # Internal helpers
@@ -87,6 +92,7 @@ class SuperKGClient:
         self, path: str, project_id: str, request, *, kind: str | None = None, timeout: float | None = None
     ) -> dict | None:
         if not self.enabled:
+            self.last_error = "superkg_disabled"
             return None
         assert_safe_to_send(request)
         payload = request.model_dump(mode="json")
@@ -97,9 +103,11 @@ class SuperKGClient:
             async with httpx.AsyncClient(base_url=self._base, timeout=timeout or self._timeout) as client:
                 resp = await client.post(f"/v1/superkg{path}", json=payload, headers=headers)
                 resp.raise_for_status()
+                self.last_error = None
                 return resp.json()
         except Exception as exc:
-            _log.debug("SuperKG proxy POST %s failed: %s", path, exc)
+            self.last_error = str(exc)
+            _log.warning("SuperKG proxy POST %s failed: %s", path, exc)
             return None
 
     async def _delete(self, path: str, project_id: str, request) -> None:

{codrspot_processor_mcp-0.1.2 → codrspot_processor_mcp-0.1.3}/src/codepreproc_client/layer1_business/mcp/server.py

@@ -164,13 +164,30 @@ async def main() -> None:
     qdrant_store = SessionVectorStore(path=settings.indexes_dir / "session_vectors")
     logger.info("session_vector_store_init path=%s", settings.indexes_dir / "session_vectors")
 
+    project_registry = ProjectRegistry(registry_data)
+
+    # bootstrap_jwt_client above was minted from a startup-time snapshot of
+    # local_projects - if the server started with zero registered projects,
+    # it stays None forever even after init_project registers one later in
+    # the same session. Cache it in a mutable holder and lazily re-mint from
+    # the *live* registry (mirroring _project_jwt_provider below) so
+    # reasoning calls succeed as soon as any project is registered, whenever
+    # that happens relative to server startup.
+    _bootstrap_jwt_holder: dict[str, object] = {"client": bootstrap_jwt_client}
+
     async def _reasoning_jwt_provider() -> str:
-        if bootstrap_jwt_client is None:
-            raise RuntimeError("no project registered yet - cannot mint a JWT for LLM reasoning calls")
-        return await bootstrap_jwt_client.get_bearer_token()
+        client = _bootstrap_jwt_holder["client"]
+        if client is None:
+            live_projects = project_registry.registry.projects
+            if not live_projects:
+                raise RuntimeError("no project registered yet - cannot mint a JWT for LLM reasoning calls")
+            _, client = await _mint_bootstrap_jwt(live_projects)
+            if client is None:
+                raise RuntimeError("no project registered yet - cannot mint a JWT for LLM reasoning calls")
+            _bootstrap_jwt_holder["client"] = client
+        return await client.get_bearer_token()
 
     llm_runtime = LLMRuntime(get_server_url(), _reasoning_jwt_provider)
-    project_registry = ProjectRegistry(registry_data)
 
     # Any /v1/superkg/* (or other project-scoped) call must present a JWT
     # naming that specific project_id in claims["project_ids"] (see