# Energy Web VCC Prover MCP

Client-side Zero-Knowledge Prover MCP server and CLI toolchain for Energy Web Verified Compute.

Powered by **NoirJS** and **bb.js** (WebAssembly). Runs completely on your local machine with **zero native C++ or nargo toolchain installations**.

---

## Features
- **Zero-Knowledge Privacy**: Private activity meter readings and CSPRNG blinding salts never leave your machine.
- **UltraHonk Proof Backend**: State-of-the-art ZK proving via `@aztec/bb.js`.
- **Pure Node.js**: Portable across macOS, Linux, and Windows (Node.js >= 20).
- **Claude Desktop & Cowork Ready**: Includes `.mcpb` manifest and stdio MCP server for immediate agent integration.

> 📖 **Comprehensive Guide**: See **[USAGE.md](USAGE.md)** for detailed CLI reference, AI agent/IDE configuration (Antigravity, Claude, Cursor), programmatic TypeScript SDK examples, and Methodology Graph submission workflows.

---

## Installation & Setup

### Option 1: Claude Desktop 1-Click Extension (.mcpb)
1. Download the latest `vcc-prover.mcpb` from [GitHub Releases](https://github.com/energywebfoundation/vcc-prover-mcp/releases).
2. Double-click the `.mcpb` file to install it directly into Claude Desktop.
3. Open Claude Desktop and start using the `status`, `prove`, and `verify` tools.

### Option 2: Add to AI Assistant Config via `npx` (Claude Desktop / Antigravity / Cursor)
Add the server definition using `npx` (requires Node.js >= 20, zero repo cloning):
- **Antigravity / Gemini IDE**: `~/.gemini/config/mcp_config.json`
- **Claude Desktop (macOS)**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Claude Desktop (Windows)**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "vcc-prover": {
      "command": "npx",
      "args": [
        "-y",
        "-p",
        "@energyweb/vcc-prover-mcp",
        "vcc-prove-mcp"
      ]
    }
  }
}
```

### Option 3: Run via CLI or Cowork / AI Coding Agents

#### A. Zero-Install via `npx` (Recommended):
```bash
# View the full usage guide directly in terminal
npx -y -p @energyweb/vcc-prover-mcp vcc-usage

# Check prover status / help
npx -y -p @energyweb/vcc-prover-mcp vcc-prove --help

# Generate a zero-knowledge proof
npx -y -p @energyweb/vcc-prover-mcp vcc-prove --recipe examples/recipe.json --input "Electricity consumed=1500.734"

# Verify a proof package locally
npx -y -p @energyweb/vcc-prover-mcp vcc-verify --recipe examples/recipe.json --package ~/.vcc/packages/<hash>.json

# Audit private disclosures against public commitments
npx -y -p @energyweb/vcc-prover-mcp vcc-audit --private ~/.vcc/private/<hash>.json --package ~/.vcc/packages/<hash>.json
```

#### B. From Cloned Repository:
```bash
git clone https://github.com/energywebfoundation/vcc-prover-mcp.git
cd vcc-prover-mcp
npm install --omit=dev

node bin/vcc-prove.js --recipe examples/recipe.json --input "Electricity consumed=1500.734"
node bin/vcc-verify.js --recipe examples/recipe.json --package ~/.vcc/packages/<hash>.json
```

### Offline / Air-Gapped CRS (Optional)

`bb.js` fetches Barretenberg's BN254 CRS (Aztec Ignition ceremony output)
over the network on first use, caching it at `~/.bb-crs/`. If your network
blocks `aztec-ignition.s3.amazonaws.com` (common on corporate proxies and
locked-down CI), proving fails instead of falling back cleanly.

To avoid the network dependency entirely, bundle the CRS into the repo once,
from a network that *can* reach that host:
```bash
npm run crs:fetch
```
This downloads the CRS into `vendor/bb-crs-home/.bb-crs/`. Once those files
are present, proving and verifying use them automatically and never touch
the network. See `vendor/bb-crs-home/.bb-crs/README.md` for details.

---

## MCP Tools Reference

| Tool | Parameters | Description |
|---|---|---|
| `status` | None | Reports NoirJS and bb.js Wasm engine status and versions. |
| `prove` | `recipe` or `recipe_path`, `inputs` | Computes Poseidon2 commitments and generates an UltraHonk proof without disclosing private readings. Takes the circuit and verifying key from the recipe. |
| `verify` | `recipe` or `recipe_path`, `package_path` or `package`, `include_proof` | Verifies the UltraHonk proof binary against the pinned verification key locally. |

The recipe is whatever `get_workspace_instructions` returned, saved to a file. It carries the
compiled circuit and the verifying key, so there is nothing to install, and the hashes those
artifacts must match, which `prove` checks before it does any work. It also carries
`submit_via`, so `submit` needs nothing but the path to the package `prove` wrote.

### Who submits

This prover holds no credential for the Methodology Graph and does not post anything to it.
The agent submits, by calling the Graph's own `submit_proof_package` with the proof as an
argument, so the ~19KB of base64 crosses a message. That means:

- call `prove` with `include_proof: true` to get the bytes,
- pass the package fields through as `prove` wrote them: `package_format_version`,
  `public_signals` (already the ordered 0x array), `formula`, `proof_sha256`, `toolchain`,
- send `proof_sha256` with the proof, always. The server checks the two against each other and
  refuses a mismatch rather than recording a round nobody can verify,
- if it does refuse, call `verify` with `include_proof: true` for a clean copy off disk. Do not
  re-prove; fresh salts make a different proof, not the same one again.

---

## Cryptographic Guarantees
- **Private Data Isolation**: Proof generation draws cryptographic blinding salts and computes commitments $C_X$ and $C_Y$ locally over BN254. Plaintext inputs and salts are written to `~/.vcc/private/<hash>.json` with restricted file permissions (`0600`).
- **Verifiable Computation**: Anyone with the public proof package can verify that the calculation adhered to the pinned formula without seeing the underlying activity volume.

---

## License
MIT License.