# correctover-mcp-server

**CCS-native MCP Server — 6-dimension runtime verification with fail-closed guarantee**

[![Version](https://img.shields.io/badge/version-1.0.0-blue.svg)]()
[![MCP Protocol](https://img.shields.io/badge/MCP-2026--07--28-green.svg)]()
[![CCS](https://img.shields.io/badge/CCS-6--dimension-orange.svg)]()
[![License](https://img.shields.io/badge/license-MIT-blue.svg)]()

---

## What is this?

`correctover-mcp-server` is an MCP (Model Context Protocol) server that embeds CCS (Correctover Conformance Standard) runtime verification directly into the protocol layer. Every tool call is verified across 6 dimensions **before** execution — if verification fails, the action is **never executed** (fail-closed).

This is not an observer-pattern governance hook. It is a protocol-level guarantee.

## Architecture

```
┌─────────────────────────────────────────────────────┐
│                    MCP Client                         │
│   (any MCP 2026-07-28 compliant client)              │
├─────────────────────────────────────────────────────┤
│              Streamable HTTP Transport                │
│   (POST /mcp, _meta version negotiation)             │
─────────────────────────────────────────────────────┤
│           CCS Runtime Verification                    │
│   ┌──────────┬──────────┬──────────┬──────────┐     │
│   │ Structure│  Schema  │  Latency │   Cost   │     │
│   │ Verifier │ Validator│  Monitor │  Monitor │     │
│   ├──────────┼──────────┼──────────┼──────────┤     │
│   │ Identity │ Integrity│  Policy  │ Failover │     │
│   │ Tracker  │  Checker │  Engine  │  Engine  │     │
│   └──────────┴──────────┴──────────┴──────────┘     │
│   ANY dimension fails → Action BLOCKED (never runs)  │
├─────────────────────────────────────────────────────┤
│                  Tool Execution                       │
│   (only reached if ALL 6 dimensions pass)            │
└─────────────────────────────────────────────────────┘
```

## 6-Dimension Verification

| Dimension | Verifies | Failure Mode |
|-----------|----------|-------------|
| **Structure** | Request has valid structure, protocol version, method | Malformed request rejected |
| **Schema** | Input matches expected tool schema | Invalid input rejected |
| **Latency** | Verification within budget (P50<10μs, P99<25μs) | Timeout → Fail-Closed |
| **Cost** | Resource usage within limits | Budget exceeded → blocked |
| **Identity** | Client is traceable (clientInfo present) | Untraceable → rejected |
| **Integrity** | Request is complete and non-empty | Corrupted → rejected |

## Quick Start

### Install

```bash
git clone https://github.com/Correctover/correctover-mcp-server.git
cd correctover-mcp-server
npm install
```

### Run

```bash
# Development
npm run dev

# Production
npm run build
npm start
```

### Configure

```bash
# Environment variables
export MCP_PORT=3000          # Default: 3000
export MCP_HOST=127.0.0.1     # Default: 127.0.0.1
export CCS_AUDIT=true         # Enable audit logging
```

## MCP Protocol Compliance

This server implements **MCP 2026-07-28 (modern-only)**:

- ✅ `server/discover` — broadcasts protocol versions, capabilities, CCS identity
- ✅ Streamable HTTP transport (POST /mcp)
- ✅ `_meta` per-request version negotiation (no initialize handshake)
- ✅ `resultType` on all responses (`complete` / `input_required`)
- ✅ MRTR pattern for human-in-the-loop (InputRequiredResult)
- ✅ `subscriptions/listen` for change notifications
- ✅ `CacheableResult` with `ttlMs` + `cacheScope`
- ✅ Standard headers (`Mcp-Method`, `Mcp-Name`, `MCP-Protocol-Version`)
- ❌ No `initialize` handshake (modern-only, no dual-era)
- ❌ No HTTP+SSE transport (deprecated)

## Available Tools

### `ccs_verify`
Run 6-dimension runtime verification on an agent action.

```json
{
  "agent_id": "agent-123",
  "action_type": "tool_call",
  "tool_name": "search_web",
  "tool_input": { "query": "test" }
}
```

### `ccs_evidence_hash`
Generate integrity evidence hash for audit chain sealing.

```json
{
  "action_id": "action-456",
  "result": { "output": "verified" },
  "verifier_id": "ccs"
}
```

### `ccs_status`
Get CCS runtime status and performance statistics.

## Available Resources

- `ccs://policy/default` — Default verification policy configuration
- `ccs://status/runtime` — Real-time runtime statistics
- `ccs://config/verifier` — Verifier configuration (latency budget, cost limits)

## CCS Extension

This server advertises the CCS extension via `server/discover`:

```json
{
  "extensions": {
    "io.modelcontextprotocol/ccs": {
      "version": "1.0.0",
      "dimensions": ["structure", "schema", "latency", "cost", "identity", "integrity"],
      "failClosed": true,
      "maxOverheadUs": 25
    }
  }
}
```

## Integration with Halo

The `ccs_evidence_hash` tool generates hashes compatible with Halo's `verification` block (v0.2.30+), enabling sealed audit chains:

```json
{
  "verification": {
    "status": "verified",
    "verifier": "ccs",
    "policy_ref": "default",
    "checked_at": "2026-08-03T12:00:00Z",
    "evidence_hash": "0x..."
  }
}
```

## Performance

- **P50 verification latency**: < 10μs
- **P99 verification latency**: < 25μs
- **Fail-closed guarantee**: Action blocked if ANY dimension fails

## Development

```bash
# Build
npm run build

# Test
npm test

# Lint
npm run lint

# Format
npm run format
```

## License

MIT

## References

- [CCS Standard (DOI: 10.5281/zenodo.21271910)](https://doi.org/10.5281/zenodo.21271910)
- [MCP 2026-07-28 Specification](https://modelcontextprotocol.io/specification/2026-07-28)
- [Halo Record](https://github.com/bkuan001/halo-record-ts)