Metadata-Version: 2.4
Name: proofflow-mcp
Version: 0.1.2
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-name: io.github.Hyperion-GPU/proofflow -->

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.
