# VeriLock MCP

`@clevertech-os/verilock-mcp` is a read-only [Model Context Protocol](https://modelcontextprotocol.io/) server for VeriLock document metadata and cryptographic evidence. It connects to the existing `https://verilock.online` API and never accepts document bytes or returns signature image bytes.

## Phase 1 tools

| Tool | Upstream route | Authentication |
| --- | --- | --- |
| `list_documents` | `GET /api/me` | Required |
| `get_document` | `GET /api/documents/:id` | Optional |
| `verify_document_hash` | `POST /api/verify/hash` | Not required |
| `get_audit_events` | `GET /api/documents/:id/events` | Required |
| `get_evidence_manifest` | `GET /api/documents/:id/evidence-manifest` | Required |
| `get_certificate` | `GET /api/documents/:id/certificate` | Not required |
| `get_chain_attestation` | `GET /api/attestations/status/:txHash` | Required |
| `get_signing_status` | Derived from `GET /api/documents/:id` | Optional |

Every tool is annotated `readOnlyHint: true`, `destructiveHint: false`, `idempotentHint: true`, and `openWorldHint: true`. Signing and all mutations remain in the VeriLock application.

## Stdio setup

```sh
npm install
npm run build
VERILOCK_TOKEN=your-verilock-session-token npm start
```

Example client configuration after cloning and building this repository:

```json
{
  "mcpServers": {
    "verilock": {
      "command": "node",
      "args": ["/absolute/path/to/verilock-mcp/dist/stdio.js"],
      "env": { "VERILOCK_TOKEN": "your-verilock-session-token" }
    }
  }
}
```

The package is prepared for a future npm release as `@clevertech-os/verilock-mcp`, but Phase 1 is currently distributed from this GitHub repository.

## Streamable HTTP setup

```sh
npm run build
npm run start:http
```

The endpoint is `POST /mcp`; health is `GET /healthz`. The HTTP entry point forwards only the current request's `Authorization: Bearer ...` header. It does not use `VERILOCK_TOKEN`, which is reserved for stdio. Put the endpoint behind HTTPS and an access control layer before exposing it outside a trusted network.

## Configuration

Copy `.env.example` to `.env` for local use. `VERILOCK_API_BASE_URL` defaults to `https://verilock.online`. HTTPS is mandatory except for `http://localhost`, `http://127.0.0.1`, and `http://[::1]`. The base URL is fixed at process startup and cannot be supplied by a tool caller. Request timeouts default to 10 seconds and response bodies default to a 1 MiB limit.

## Privacy and security

The server forwards the session token only to the configured VeriLock API and never logs it. Upstream errors are sanitized before being returned to an MCP client. Auth-required calls fail locally when no token is present. Hash verification accepts only a 64-character hexadecimal SHA-256 digest. URL path parameters are encoded as one segment. Keep tokens in environment secrets, use TLS, and grant MCP clients only the access they need.

## Deployment

The included `Dockerfile` runs the HTTP transport on port 8787 as the unprivileged `node` user. A typical deployment sets `VERILOCK_API_BASE_URL`, configures a TLS reverse proxy, and restricts `/mcp` to intended clients. Do not put a long-lived user token in a public URL or image layer.

The container sets `VERILOCK_HTTP_HOST=0.0.0.0` so its published port is reachable. The non-container default remains `127.0.0.1` for safer local development.

## Development

```sh
npm install
npm run format
npm run build
npm test
npm audit --omit=dev
```

See [CONTRIBUTING.md](CONTRIBUTING.md) and [SECURITY.md](SECURITY.md).