@peac/mcp-server 0.10.13 → 0.11.2

package/README.md

@@ -1,6 +1,6 @@
 # @peac/mcp-server
 
-Verify, issue, and bundle PEAC receipts in any MCP client (Claude Desktop, Cursor, Windsurf) -- locally, offline, no API keys.
+Verify, issue, and bundle PEAC receipts in any MCP client (Claude Desktop, Cursor, Windsurf): locally, offline, no API keys.
 
 ## Quick Start
 
@@ -117,13 +117,13 @@ Note: stdout is reserved for JSON-RPC messages. All diagnostics, banners, and er
 
 ## Two Operating Modes
 
-**Pure mode** (default) -- verify, inspect, and decode receipts anywhere. No keys, no filesystem writes, no configuration needed. Safe for any environment.
+**Pure mode** (default): verify, inspect, and decode receipts anywhere. No keys, no filesystem writes, no configuration needed. Safe for any environment.
 
 ```bash
 npx -y @peac/mcp-server
 ```
 
-**Issuer mode** -- additionally issue receipts and create signed evidence bundles. Requires explicit operator opt-in via CLI flags. Privileged tools are only visible and callable when their prerequisites are configured:
+**Issuer mode**: additionally issue receipts and create signed evidence bundles. Requires explicit operator opt-in via CLI flags. Privileged tools are only visible and callable when their prerequisites are configured:
 
 - `--issuer-key` + `--issuer-id` enables `peac_issue`
 - `--bundle-dir` additionally enables `peac_create_bundle`
@@ -135,7 +135,36 @@ npx -y @peac/mcp-server \
   --bundle-dir ./bundles
 ```
 
-Evidence bundles are self-contained directories with canonical manifests (sorted keys, SHA-256 receipt hashes, content-addressable `bundle_id`) and signed provenance (`manifest.jws`). The `bundle_id` is deterministic -- same receipts and policy always produce the same ID regardless of when the bundle is created. Manifest content includes `created_at`, so the signature differs across runs. Bundles can be verified offline, diffed, cached, and used for audits, disputes, or SOC 2 evidence collection.
+Evidence bundles are self-contained directories with canonical manifests (sorted keys, SHA-256 receipt hashes, content-addressable `bundle_id`) and signed provenance (`manifest.jws`). The `bundle_id` is deterministic: same receipts and policy always produce the same ID regardless of when the bundle is created. Manifest content includes `created_at`, so the signature differs across runs. Bundles can be verified offline, diffed, cached, and used for audits, disputes, or SOC 2 evidence collection.
+
+## Transports
+
+### stdio (default)
+
+Standard MCP transport for local/CLI usage. JSON-RPC over stdin/stdout.
+
+```bash
+npx -y @peac/mcp-server
+```
+
+### Streamable HTTP (v0.11.0+)
+
+Remote transport for network-accessible MCP servers. Session-isolated with per-session `McpServer` + transport pairs (CVE-2026-25536 defense).
+
+```bash
+npx -y @peac/mcp-server --transport http --port 3000
+```
+
+Endpoints:
+
+- `POST /mcp`: JSON-RPC tool calls (requires `Mcp-Session-Id` after initialization)
+- `DELETE /mcp`: terminate session
+- `GET /health`: health check (no auth)
+- `GET /.well-known/oauth-protected-resource[/<path>]`: RFC 9728 PRM (when configured)
+
+Security defaults: localhost-only bind, CORS deny-all, 1MB request body limit, per-session + per-IP rate limiting (100 req/min), session TTL (30 min), max 100 concurrent sessions.
+
+See [HTTP Transport Security](../../docs/security/HTTP-TRANSPORT-SECURITY.md) for the full security model.
 
 ## CLI Options
 
@@ -143,13 +172,20 @@ Evidence bundles are self-contained directories with canonical manifests (sorted
 peac-mcp-server [options]
 
 Options:
-  --issuer-key <ref>   Issuer signing key (env:VAR or file:/path to Ed25519 JWK)
-  --issuer-id <uri>    Issuer identifier URI (required with --issuer-key)
-  --bundle-dir <path>  Directory for evidence bundle output
-  --policy <path>      Policy configuration file (JSON)
-  --jwks-file <path>   JWKS file for verifier key resolution
-  -V, --version        Output version number
-  -h, --help           Display help
+  --issuer-key <ref>          Issuer signing key (env:VAR or file:/path to Ed25519 JWK)
+  --issuer-id <uri>           Issuer identifier URI (required with --issuer-key)
+  --bundle-dir <path>         Directory for evidence bundle output
+  --policy <path>             Policy configuration file (JSON)
+  --jwks-file <path>          JWKS file for verifier key resolution
+  --transport <type>          Transport: stdio (default) or http
+  --port <number>             HTTP port (default: 3000, http only)
+  --host <address>            HTTP bind address (default: 127.0.0.1)
+  --cors-origins <list>       Allowed CORS origins (comma-separated)
+  --authorization-servers <l> OAuth authorization server URIs (enables PRM)
+  --public-url <url>          Canonical public URL (required for PRM)
+  --trust-proxy <preset>      Trust X-Forwarded-For (off/loopback/linklocal/private/all)
+  -V, --version               Output version number
+  -h, --help                  Display help
 ```
 
 ## Policy Configuration
@@ -199,7 +235,7 @@ const result = await handleVerify({
   input: { jws: 'eyJ...', public_key_base64url: '...' },
   policy,
   context: {
-    version: '0.10.13',
+    version: '0.11.0',
     policyHash,
     protocolVersion: '2025-11-25',
   },
@@ -212,17 +248,75 @@ if (result.structured.ok) {
 
 ## MCP SDK Compatibility
 
-This package pins `@modelcontextprotocol/sdk` with a tilde range (patch-only updates). The SDK and workspace may use different Zod versions; schemas are structurally compatible at runtime. If upgrading the SDK, verify tool registration still works by running `pnpm --filter @peac/mcp-server test`. See `package.json` for actual pinned versions.
+This package pins `@modelcontextprotocol/sdk` at `~1.27.0` (>= 1.26.0 required for CVE-2026-25536 fix). The SDK peer dependency accepts Zod `^3.25 || ^4.0`; the workspace uses Zod 4. If upgrading the SDK, verify tool registration still works by running `pnpm --filter @peac/mcp-server test`. See `package.json` for actual pinned versions.
+
+## How to Verify a Receipt
+
+1. Add the MCP server to your agent (see Quick Start above).
+2. Provide the receipt JWS and a public key (base64url-encoded Ed25519).
+3. Call `peac_verify` and check the `ok` field in the response.
+
+```text
+> "Verify this receipt: eyJhbGci... with public key MCowBQYDK2..."
+```
+
+The tool returns structured content with `ok: true/false`, claim details, and the verification report.
+
+## How to Issue a Receipt
+
+Issuance requires an Ed25519 signing key. Start the server with `--issuer-key` and `--issuer-id`:
+
+```bash
+npx -y @peac/mcp-server --issuer-key env:PEAC_KEY --issuer-id https://your-service.example.com
+```
+
+Then call `peac_issue` with the receipt claims (amount, currency, rail, reference, audience).
+
+## Use with Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "peac": {
+      "command": "npx",
+      "args": ["-y", "@peac/mcp-server"]
+    }
+  }
+}
+```
+
+Restart Claude Desktop. The PEAC tools appear in the tool picker.
+
+## Use with Cursor
+
+Add to `.cursor/mcp.json` at your project root:
+
+```json
+{
+  "mcpServers": {
+    "peac": {
+      "command": "npx",
+      "args": ["-y", "@peac/mcp-server"]
+    }
+  }
+}
+```
+
+Restart Cursor. PEAC tools are available in chat.
 
 ## Architecture
 
 - **DD-51**: Pure handlers with no MCP SDK dependency
-- **DD-52**: No ambient key discovery -- explicit `--issuer-key` only
+- **DD-52**: No ambient key discovery: explicit `--issuer-key` only
 - **DD-53**: Static policy loaded once at startup with SHA-256 hash
 - **DD-54**: Structured outputs (`structuredContent` + `text`) on every response
 - **DD-55**: No URLs resolved from tool inputs (SSRF prevention)
 - **DD-57**: Core modules (`handlers/`, `schemas/`, `infra/`) have zero MCP SDK imports
-- **DD-58**: Line-buffered stdout fence validates JSON-RPC 2.0 output
+- **DD-58**: Line-buffered stdout fence validates JSON-RPC 2.0 output (stdio only)
+- **DD-119**: Streamable HTTP as additive remote transport (session-isolated)
+- **DD-123**: HTTP security boundaries (CORS, rate limiting, Origin/Host validation)
 
 ## License