proofflow-mcp 0.1.0__tar.gz

proofflow_mcp-0.1.0/.gitignore

@@ -0,0 +1,24 @@
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+.pytest_cache/
+
+# Local data
+*.sqlite3
+*.db
+backend/data/demo/
+sample_data/work/
+sample_data/repos/
+
+# Frontend
+node_modules/
+dist/
+.vite/
+*.tsbuildinfo
+
+# OS and editor files
+.DS_Store
+Thumbs.db
+.idea/
+.vscode/

proofflow_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,169 @@
+Metadata-Version: 2.4
+Name: proofflow-mcp
+Version: 0.1.0
+Summary: MCP server for ProofFlow – audit infrastructure for AI coding agents
+Project-URL: Homepage, https://github.com/Hyperion-GPU/ProofFlow-v0.1
+Project-URL: Repository, https://github.com/Hyperion-GPU/ProofFlow-v0.1
+Project-URL: Issues, https://github.com/Hyperion-GPU/ProofFlow-v0.1/issues
+Author: Hyperion-GPU
+License-Expression: MIT
+Keywords: ai-agent,audit,claude-code,codex,mcp,proofflow
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: mcp>=1.0.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# ProofFlow MCP Server
+
+MCP (Model Context Protocol) server that exposes ProofFlow's audit capabilities as tools for Claude Code and Codex.
+
+## What it does
+
+Lets AI coding assistants trigger ProofFlow workflows directly:
+
+- **Scan folders** — index files with SHA-256 hashes, create audit Cases
+- **Code review** — analyze git diffs, generate evidence-backed risk claims
+- **Suggest actions** — generate file organization suggestions
+- **Approve & execute** — run pending actions (with policy gate awareness)
+- **Export Proof Packets** — generate shareable markdown audit reports
+- **Search** — full-text search across indexed artifacts
+- **Undo** — reverse executed actions
+
+## Prerequisites
+
+- Python 3.11+
+- ProofFlow backend running on `http://127.0.0.1:8787`
+
+## Installation
+
+```bash
+cd mcp-server
+pip install -e .
+```
+
+For development (includes test dependencies):
+
+```bash
+pip install -e ".[dev]"
+```
+
+> Note: Install in a separate virtualenv from the backend to avoid starlette version conflicts between FastAPI and the MCP SDK.
+
+## Configuration
+
+### Claude Code
+
+Add to your project's `.mcp.json` or `~/.claude/settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "proofflow": {
+      "command": "python",
+      "args": ["-m", "proofflow_mcp"],
+      "env": {
+        "PROOFFLOW_BASE_URL": "http://127.0.0.1:8787"
+      }
+    }
+  }
+}
+```
+
+### Claude Desktop
+
+Add to `claude_desktop_config.json`:
+- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "proofflow": {
+      "command": "proofflow-mcp",
+      "env": {
+        "PROOFFLOW_BASE_URL": "http://127.0.0.1:8787"
+      }
+    }
+  }
+}
+```
+
+### Codex
+
+Add to your Codex MCP configuration with the same command/args pattern.
+
+### Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `PROOFFLOW_BASE_URL` | `http://127.0.0.1:8787` | ProofFlow backend URL |
+| `PROOFFLOW_TIMEOUT` | `30` | HTTP request timeout in seconds |
+| `PROOFFLOW_API_KEY` | *(unset)* | API key for backend auth (optional) |
+| `PROOFFLOW_MCP_MAX_CONCURRENT` | `5` | Max concurrent MCP tool calls |
+
+## Available Tools
+
+| Tool | Description |
+|------|-------------|
+| `proofflow_health` | Check backend connectivity |
+| `proofflow_scan` | Scan a folder, create Case + Artifacts |
+| `proofflow_suggest` | Generate cleanup suggestions for a scanned Case |
+| `proofflow_review` | AgentGuard code review on a git repo |
+| `proofflow_status` | Get full Case status (artifacts, claims, actions) |
+| `proofflow_approve_execute` | Approve and execute a pending action |
+| `proofflow_export_packet` | Export Case as Proof Packet (markdown) |
+| `proofflow_search` | Full-text search across artifacts |
+| `proofflow_list_cases` | List all Cases |
+| `proofflow_list_actions` | List actions for a Case |
+| `proofflow_undo` | Undo an executed action |
+| `proofflow_decide` | Create a decision to approve/reject a policy gate |
+
+## Usage Example
+
+In Claude Code, once configured:
+
+```
+> Review the code changes in this repo for safety
+
+Claude will call proofflow_review with the current repo path,
+creating an AgentGuard Case with evidence-backed claims.
+```
+
+## Running Tests
+
+```bash
+cd mcp-server
+python -m pytest tests/ -v
+```
+
+## Running the Server Directly
+
+```bash
+python -m proofflow_mcp
+```
+
+The server communicates via stdio (stdin/stdout) per the MCP protocol.
+
+## Architecture
+
+```
+Claude Code / Codex
+    ↓ (MCP stdio)
+ProofFlow MCP Server
+    ↓ (HTTP)
+ProofFlow Backend (localhost:8787)
+    ↓
+SQLite DB + Local Files
+```
+
+The MCP server is a thin adapter — all business logic lives in the ProofFlow backend.

proofflow_mcp-0.1.0/README.md

@@ -0,0 +1,144 @@
+# ProofFlow MCP Server
+
+MCP (Model Context Protocol) server that exposes ProofFlow's audit capabilities as tools for Claude Code and Codex.
+
+## What it does
+
+Lets AI coding assistants trigger ProofFlow workflows directly:
+
+- **Scan folders** — index files with SHA-256 hashes, create audit Cases
+- **Code review** — analyze git diffs, generate evidence-backed risk claims
+- **Suggest actions** — generate file organization suggestions
+- **Approve & execute** — run pending actions (with policy gate awareness)
+- **Export Proof Packets** — generate shareable markdown audit reports
+- **Search** — full-text search across indexed artifacts
+- **Undo** — reverse executed actions
+
+## Prerequisites
+
+- Python 3.11+
+- ProofFlow backend running on `http://127.0.0.1:8787`
+
+## Installation
+
+```bash
+cd mcp-server
+pip install -e .
+```
+
+For development (includes test dependencies):
+
+```bash
+pip install -e ".[dev]"
+```
+
+> Note: Install in a separate virtualenv from the backend to avoid starlette version conflicts between FastAPI and the MCP SDK.
+
+## Configuration
+
+### Claude Code
+
+Add to your project's `.mcp.json` or `~/.claude/settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "proofflow": {
+      "command": "python",
+      "args": ["-m", "proofflow_mcp"],
+      "env": {
+        "PROOFFLOW_BASE_URL": "http://127.0.0.1:8787"
+      }
+    }
+  }
+}
+```
+
+### Claude Desktop
+
+Add to `claude_desktop_config.json`:
+- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "proofflow": {
+      "command": "proofflow-mcp",
+      "env": {
+        "PROOFFLOW_BASE_URL": "http://127.0.0.1:8787"
+      }
+    }
+  }
+}
+```
+
+### Codex
+
+Add to your Codex MCP configuration with the same command/args pattern.
+
+### Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `PROOFFLOW_BASE_URL` | `http://127.0.0.1:8787` | ProofFlow backend URL |
+| `PROOFFLOW_TIMEOUT` | `30` | HTTP request timeout in seconds |
+| `PROOFFLOW_API_KEY` | *(unset)* | API key for backend auth (optional) |
+| `PROOFFLOW_MCP_MAX_CONCURRENT` | `5` | Max concurrent MCP tool calls |
+
+## Available Tools
+
+| Tool | Description |
+|------|-------------|
+| `proofflow_health` | Check backend connectivity |
+| `proofflow_scan` | Scan a folder, create Case + Artifacts |
+| `proofflow_suggest` | Generate cleanup suggestions for a scanned Case |
+| `proofflow_review` | AgentGuard code review on a git repo |
+| `proofflow_status` | Get full Case status (artifacts, claims, actions) |
+| `proofflow_approve_execute` | Approve and execute a pending action |
+| `proofflow_export_packet` | Export Case as Proof Packet (markdown) |
+| `proofflow_search` | Full-text search across artifacts |
+| `proofflow_list_cases` | List all Cases |
+| `proofflow_list_actions` | List actions for a Case |
+| `proofflow_undo` | Undo an executed action |
+| `proofflow_decide` | Create a decision to approve/reject a policy gate |
+
+## Usage Example
+
+In Claude Code, once configured:
+
+```
+> Review the code changes in this repo for safety
+
+Claude will call proofflow_review with the current repo path,
+creating an AgentGuard Case with evidence-backed claims.
+```
+
+## Running Tests
+
+```bash
+cd mcp-server
+python -m pytest tests/ -v
+```
+
+## Running the Server Directly
+
+```bash
+python -m proofflow_mcp
+```
+
+The server communicates via stdio (stdin/stdout) per the MCP protocol.
+
+## Architecture
+
+```
+Claude Code / Codex
+    ↓ (MCP stdio)
+ProofFlow MCP Server
+    ↓ (HTTP)
+ProofFlow Backend (localhost:8787)
+    ↓
+SQLite DB + Local Files
+```
+
+The MCP server is a thin adapter — all business logic lives in the ProofFlow backend.

proofflow_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,48 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "proofflow-mcp"
+version = "0.1.0"
+description = "MCP server for ProofFlow – audit infrastructure for AI coding agents"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.11"
+authors = [
+    { name = "Hyperion-GPU" },
+]
+keywords = ["mcp", "proofflow", "audit", "ai-agent", "claude-code", "codex"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Quality Assurance",
+]
+dependencies = [
+    "mcp>=1.0.0",
+    "httpx>=0.27.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/Hyperion-GPU/ProofFlow-v0.1"
+Repository = "https://github.com/Hyperion-GPU/ProofFlow-v0.1"
+Issues = "https://github.com/Hyperion-GPU/ProofFlow-v0.1/issues"
+
+[project.scripts]
+proofflow-mcp = "proofflow_mcp.server:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/proofflow_mcp"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+    "respx>=0.21",
+]

proofflow_mcp-0.1.0/src/proofflow_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""ProofFlow MCP Server – exposes ProofFlow audit tools via Model Context Protocol."""
+
+__version__ = "0.1.0"

proofflow_mcp-0.1.0/src/proofflow_mcp/__main__.py

@@ -0,0 +1,5 @@
+"""Allow running as python -m proofflow_mcp."""
+
+from proofflow_mcp.server import main
+
+main()

proofflow_mcp-0.1.0/src/proofflow_mcp/client.py

@@ -0,0 +1,175 @@
+"""HTTP client wrapper for the ProofFlow backend REST API."""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+import httpx
+
+
+class ProofFlowError(Exception):
+    """Raised when a ProofFlow API call fails."""
+
+    def __init__(self, message: str, status_code: int | None = None):
+        super().__init__(message)
+        self.status_code = status_code
+
+
+class ProofFlowClient:
+    """Async HTTP client for the ProofFlow backend."""
+
+    def __init__(self) -> None:
+        self._base_url = os.getenv("PROOFFLOW_BASE_URL", "http://127.0.0.1:8787")
+        self._timeout = float(os.getenv("PROOFFLOW_TIMEOUT", "30"))
+        self._http: httpx.AsyncClient | None = None
+
+    async def _get_http(self) -> httpx.AsyncClient:
+        if self._http is None or self._http.is_closed:
+            headers: dict[str, str] = {}
+            api_key = os.getenv("PROOFFLOW_API_KEY")
+            if api_key:
+                headers["X-ProofFlow-Token"] = api_key
+            self._http = httpx.AsyncClient(
+                base_url=self._base_url, timeout=self._timeout, headers=headers
+            )
+        return self._http
+
+    async def close(self) -> None:
+        if self._http and not self._http.is_closed:
+            await self._http.aclose()
+
+    async def _request(
+        self, method: str, path: str, **kwargs: Any
+    ) -> dict[str, Any] | list[dict[str, Any]]:
+        http = await self._get_http()
+        try:
+            response = await http.request(method, path, **kwargs)
+        except httpx.ConnectError:
+            raise ProofFlowError(
+                "ProofFlow backend is not running. "
+                "Start it with: cd backend && python -m uvicorn proofflow.main:app --port 8787"
+            )
+        except httpx.TimeoutException:
+            raise ProofFlowError(
+                f"ProofFlow backend timed out after {self._timeout}s"
+            )
+
+        if response.status_code >= 400:
+            try:
+                detail = response.json().get("detail", response.text)
+            except Exception:
+                detail = response.text
+            raise ProofFlowError(
+                f"ProofFlow API error ({response.status_code}): {detail}",
+                status_code=response.status_code,
+            )
+
+        return response.json()
+
+    # --- Health ---
+
+    async def health(self) -> dict[str, Any]:
+        return await self._request("GET", "/health")
+
+    # --- Cases ---
+
+    async def list_cases(self) -> list[dict[str, Any]]:
+        return await self._request("GET", "/cases")
+
+    async def get_case_packet(self, case_id: str) -> dict[str, Any]:
+        return await self._request("GET", f"/cases/{case_id}/packet")
+
+    # --- LocalProof ---
+
+    async def scan(
+        self,
+        folder_path: str,
+        recursive: bool = True,
+        max_files: int = 500,
+    ) -> dict[str, Any]:
+        return await self._request(
+            "POST",
+            "/localproof/scan",
+            json={"folder_path": folder_path, "recursive": recursive, "max_files": max_files},
+        )
+
+    async def suggest_actions(
+        self, case_id: str, target_root: str
+    ) -> dict[str, Any]:
+        return await self._request(
+            "POST",
+            "/localproof/suggest-actions",
+            json={"case_id": case_id, "target_root": target_root},
+        )
+
+    # --- AgentGuard ---
+
+    async def review(
+        self,
+        repo_path: str,
+        base_ref: str = "HEAD",
+        include_untracked: bool = True,
+        test_command: str | None = None,
+    ) -> dict[str, Any]:
+        body: dict[str, Any] = {
+            "repo_path": repo_path,
+            "base_ref": base_ref,
+            "include_untracked": include_untracked,
+        }
+        if test_command is not None:
+            body["test_command"] = test_command
+        return await self._request("POST", "/agentguard/review", json=body)
+
+    # --- Actions ---
+
+    async def list_actions(self, case_id: str) -> list[dict[str, Any]]:
+        return await self._request("GET", f"/cases/{case_id}/actions")
+
+    async def approve_action(self, action_id: str) -> dict[str, Any]:
+        return await self._request("POST", f"/actions/{action_id}/approve")
+
+    async def execute_action(self, action_id: str) -> dict[str, Any]:
+        return await self._request("POST", f"/actions/{action_id}/execute")
+
+    async def undo_action(self, action_id: str) -> dict[str, Any]:
+        return await self._request("POST", f"/actions/{action_id}/undo")
+
+    # --- Reports ---
+
+    async def export_report(self, case_id: str) -> dict[str, Any]:
+        return await self._request(
+            "POST",
+            f"/reports/cases/{case_id}/export",
+            json={"format": "markdown"},
+        )
+
+    # --- Search ---
+
+    async def search(self, query: str, limit: int = 25) -> dict[str, Any]:
+        return await self._request(
+            "GET", "/search", params={"q": query, "limit": limit}
+        )
+
+    # --- Decisions ---
+
+    async def create_decision(
+        self,
+        case_id: str,
+        title: str,
+        status: str,
+        rationale: str,
+        result: str,
+        metadata: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        body: dict[str, Any] = {
+            "title": title,
+            "status": status,
+            "rationale": rationale,
+            "result": result,
+        }
+        if metadata:
+            body["metadata"] = metadata
+        return await self._request(
+            "POST", f"/cases/{case_id}/decisions", json=body
+        )