Metadata-Version: 2.4
Name: correctover-ccs-mcp
Version: 1.0.0
Summary: Correctover CCS MCP Server — local-first MCP/Agent security tooling: receipt verification, batch audit, field-level tamper localization, and 14-rule MCP config checkup. Zero network egress, zero third-party dependencies.
Author-email: Correctover <wangguigui@correctover.com>
License-Expression: LicenseRef-Elastic-2.0
Project-URL: Homepage, https://correctover.com
Project-URL: Documentation, https://correctover.com/docs
Project-URL: Repository, https://github.com/DSHCorrectover/ccs-conformance-vectors
Project-URL: Issues, https://correctover.com/support
Project-URL: Changelog, https://correctover.com/docs/changelog
Keywords: mcp,model-context-protocol,security,agent-security,ed25519,receipt-verification,tamper-detection,forensics,llm,ai-agent,supply-chain
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Typing :: Typed
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# correctover-ccs-mcp

**Correctover CCS MCP Server** — local-first MCP/Agent security tooling, exposed as MCP tools for Claude Desktop, Cursor, Cline, Windsurf, and any MCP client.

**Zero network egress. Zero third-party dependencies. Data never leaves your machine.**

[![MCP](https://img.shields.io/badge/MCP-compatible-blue)](https://modelcontextprotocol.io)
[![License](https://img.shields.io/badge/license-Elastic--2.0-green)](./LICENSE)
[![Python](https://img.shields.io/badge/python-3.9%2B-blue)](https://www.python.org)

---

## Why this exists

Every verification tool in this space gives you the same two-word answer: `PASS` or `FAIL`.

That is not enough when you actually have to resolve an incident. When a signed agent decision record has been altered, you do not need to know *that* something changed — you need to know **which field, on which layer, changed from what to what**.

This server exposes four tools, one of which does exactly that.

| Tool | What it does | Who else does it |
|---|---|---|
| `ccs_locate_tampering` | **Field-level tamper localization** — returns RFC 6901 JSON-Pointer paths, before/after values, and severity grading | ❌ Nobody (see below) |
| `ccs_verify_receipt` | Ed25519 signature + RFC 8785 JCS + SHA-256 + schema verification | ✅ Many |
| `ccs_audit_batch` | Batch audit up to 200 receipts, pass rate, tamper index list, optional hash-chain check | ⚠️ Few |
| `ccs_checkup_mcp_config` | 14-rule static security checkup on MCP/Agent configs | ⚠️ Some |

### The differentiator, concretely

Given an original receipt and a suspect copy, `ccs_locate_tampering` returns this — not a boolean:

```
  critical  path=/checks/security/detail   (dotted: checks.security.detail)
  critical  path=/checks/security/status   (dotted: checks.security.status)
  high      path=/reason                   (dotted: reason)
  critical  path=/verdict                  (dotted: verdict)
```

Sigstore, C2PA, and comparable tools return only `signatureValid: false`. That tells you the artifact is bad. It does not tell you what to fix, or what to argue in a dispute.

---

## Install

```bash
pip install correctover-ccs-mcp
```

Or from source:

```bash
git clone https://github.com/DSHCorrectover/ccs-conformance-vectors
cd ccs-conformance-vectors/ccs-mcp-server/correctover-ccs-mcp
pip install -e .
```

## Configure your MCP client

**Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS,
`%APPDATA%\Claude\claude_desktop_config.json` on Windows):

```json
{
  "mcpServers": {
    "correctover-ccs": {
      "command": "correctover-ccs-mcp"
    }
  }
}
```

**Cursor / Cline / Windsurf** use the same `mcpServers` shape. If you prefer to run it without installing:

```json
{
  "mcpServers": {
    "correctover-ccs": {
      "command": "python",
      "args": ["/absolute/path/to/correctover_ccs_mcp/server.py"]
    }
  }
}
```

### Providing public keys

CCS receipts carry `public_key_id`, **not** an inline public key — a self-declared key is not a trust root. Supply the key in whichever way fits your setup:

| Method | How |
|---|---|
| Tool argument | `public_key_pem` parameter on `ccs_verify_receipt` / `ccs_audit_batch` |
| Environment variable | `CCS_PUBLIC_KEY` — the PEM text directly |
| Key directory | `CCS_PUBKEY_DIR` — looks up `<public_key_id>.pem` |

If no key resolves, verification **fails closed** with a message telling you the `public_key_id` to fetch. It never assumes.

---

## Usage examples

### Localize tampering

> *"Compare `original.json` and `suspect-receipt.json` and tell me exactly what was changed."*

```json
{
  "name": "ccs_locate_tampering",
  "arguments": {
    "original": { "...": "..." },
    "suspect":  { "...": "..." }
  }
}
```

### Audit a batch with hash-chain checking

```json
{
  "name": "ccs_audit_batch",
  "arguments": {
    "batch": { "receipts": [ "...", "..." ] },
    "check_chain": true
  }
}
```

Returns `total` / `valid` / `invalid` / `pass_rate` / `tampered_indexes` / `fail_reason_distribution`, plus `chain_check` when requested.

### Check up an MCP config before you run it

```json
{
  "name": "ccs_checkup_mcp_config",
  "arguments": { "config": { "mcpServers": { "...": {} } } }
}
```

Returns `risk_level` plus per-finding `rule_id`, `severity` (CRIT/HIGH/MED/LOW), `evidence`, and `remediation`.

---

## Verify this package yourself

Nothing here asks for your trust. Three commands:

```bash
# 1. Offline self-test — runs all four tools against bundled examples
python -m correctover_ccs_mcp.server --selftest

# 2. Full test suite (42 tests, incl. real MCP subprocess handshake)
python -m pytest tests/ -v

# 3. Inspect the tool contracts without connecting a client
python -m correctover_ccs_mcp.server --list-tools
```

All four tools are exercised in both directions — valid inputs must pass, and tampered, wrong-key, and missing-key inputs must be **rejected**, not silently allowed.

---

## Tool reference

### `ccs_verify_receipt`

| | |
|---|---|
| Required | `receipt` (object) |
| Optional | `public_key_pem` (string) |
| Returns | `valid`, `verdict`, `public_key_source`, full `result.evidence` (JCS byte count, SHA-256 digest, content-hash match, Ed25519 status, schema check) |

### `ccs_audit_batch`

| | |
|---|---|
| Required | `batch` (array, or `{"receipts": [...]}`) |
| Optional | `check_chain` (bool, default `false`), `public_key_pem` (string) |
| Limit | 200 receipts per call — **hard cap, oversized batches are rejected, never truncated** |
| Returns | `total`, `valid`, `invalid`, `pass_rate`, `tampered_indexes`, `fail_reason_distribution`, per-receipt `results`, plus `chain_check` when requested |

### `ccs_checkup_mcp_config`

| | |
|---|---|
| Required | `config` (object) |
| Accepts | `{"mcpServers": {...}}`, `{"config": {"mcpServers": {...}}}`, or a bare `{name: {...}}` map |
| Returns | `risk_level`, `summary` (per-severity counts), `findings[]` with `rule_id` / `severity` / `evidence` / `remediation` |

Covers hardcoded credentials, arbitrary command execution, writable filesystem mounts, SSRF surface, cleartext HTTP, unpinned package runners, and more.

### `ccs_locate_tampering`

| | |
|---|---|
| Required | `original` (object), `suspect` (object) |
| Returns | `tampered` (bool), `changes[]` with `path` (**RFC 6901 JSON-Pointer**), `path_dotted` (original form), `change` type, `original` / `suspect` values, `severity`, `remediation` |

---

## Design decisions worth knowing

**Fail-closed, not fail-open.** Missing public key, unparseable config, oversized batch, malformed diff input — every one of these returns an explicit error. There is no path where a malformed input produces an affirmative verification result.

**No network imports.** The server source imports no HTTP or socket libraries. This is enforced by a test, not just a promise: `test_no_network_imports` fails the build if one is introduced.

**Evidence, not verdicts.** `ccs_verify_receipt` returns the JCS canonical byte count, the recomputed SHA-256, the content-hash comparison result, and the raw Ed25519 status. You can audit our reasoning rather than accept our conclusion.

**JSON-Pointer at the boundary.** The engine internally uses dotted paths; the MCP boundary normalizes to RFC 6901 and keeps the dotted form in `path_dotted`. Converted, not replaced.

**No third-party dependencies.** Ed25519, JCS canonicalization, and SHA-256 are implemented against the Python standard library. `pip install` pulls nothing else.

---

## What this tool does NOT do

- **It does not establish trust in a public key.** It verifies that a signature matches a key you supplied. Where that key came from is your problem, and rightly so.
- **It does not prove business impact.** A receipt can be cryptographically pristine and describe something that should never have happened. Signature validity and correctness of the underlying action are different questions.
- **It does not replace human audit.** The 14-rule checkup is a fast static triage over config documents. Runtime behavior, tool implementation code, permission boundaries, and data flows require manual review.
- **It does not provide third-party dated attestation.** That is a separate, optional service. Everything here runs locally and produces a local verdict.

---

## License

**Elastic License 2.0** — see [LICENSE](./LICENSE).

Open standard, proprietary engine. You may use, copy, distribute, and modify this software.
You may not provide it to third parties as a hosted or managed service.

---

## Support

- Documentation — <https://correctover.com/docs>
- Issues — <https://correctover.com/support>

---

*Correctover — AI Reliability*
