@clearedby/mcp 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Morecheckouts Limited
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,43 @@
+# @clearedby/mcp
+
+A [Model Context Protocol](https://modelcontextprotocol.io) server that lets an AI agent (Claude Code/Desktop, or any MCP client) gate its own consequential actions through [ClearedBy](https://clearedby.com).
+
+## Tools
+
+| Tool | What it does |
+|------|--------------|
+| `request_clearance` | Gate an action. Returns **cleared** (safe to proceed), **rejected** (do NOT proceed, with the reason), or — if held for a human — waits up to 10 minutes for the decision. |
+| `check_policy` | Dry-run: preview what the policy *would* decide, recording nothing. |
+| `get_ledger` | Recent entries from the tamper-evident attestation ledger. |
+
+## Run it
+
+```bash
+CLEAREDBY_API_KEY=cb_live_… npx @clearedby/mcp
+```
+
+Optional: `CLEAREDBY_BASE_URL` (defaults to `https://app.clearedby.com`).
+
+### Claude Desktop / Claude Code config
+
+```jsonc
+{
+  "mcpServers": {
+    "clearedby": {
+      "command": "npx",
+      "args": ["@clearedby/mcp"],
+      "env": { "CLEAREDBY_API_KEY": "cb_live_…" }
+    }
+  }
+}
+```
+
+## Example
+
+> **Agent:** I'm about to issue a £400 refund on order SO-118.
+> *calls `request_clearance { action: "refund.create", params: { amount: 400, order: "SO-118" } }`*
+> **ClearedBy:** ⛔ Rejected by a reviewer: "Refund exceeds the 30-day window." Do NOT proceed.
+
+The agent never decides for itself — policy clears the safe ones and a human handles the rest, and every decision is signed into your org's audit chain.
+
+Built on [`@clearedby/sdk`](../sdk).

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+// ClearedBy MCP server (CLE-20). Exposes three tools to any MCP client
+// (Claude Code/Desktop, etc.): request_clearance, check_policy, get_ledger.
+// Reads CLEAREDBY_API_KEY; talks to the gate via @clearedby/sdk over stdio.
+//
+//   CLEAREDBY_API_KEY=cb_live_… npx @clearedby/mcp
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { ClearedBy } from '@clearedby/sdk';
+import { checkPolicy, getLedger, requestClearance } from './tools.js';
+async function main() {
+    const apiKey = process.env.CLEAREDBY_API_KEY;
+    if (!apiKey) {
+        console.error('CLEAREDBY_API_KEY is required');
+        process.exit(1);
+    }
+    const cb = new ClearedBy({ apiKey, baseUrl: process.env.CLEAREDBY_BASE_URL });
+    const server = new McpServer({ name: 'clearedby', version: '0.0.1' });
+    server.tool('request_clearance', 'Gate a consequential action before doing it. Returns whether it is cleared (safe to proceed), rejected (do NOT proceed), or — if held for a human — waits up to 10 minutes for a decision.', {
+        action: z.string().describe('e.g. refund.create, ad.launch'),
+        params: z.record(z.unknown()).optional().describe('the action parameters, e.g. { amount: 250 }'),
+        policy: z.string().optional(),
+        summary: z.string().optional().describe('one-line human summary for the reviewer'),
+    }, async (args) => {
+        const r = await requestClearance(cb, args);
+        return { content: [{ type: 'text', text: r.text }], isError: r.isError, structuredContent: r.structured };
+    });
+    server.tool('check_policy', 'Dry-run: preview what the policy WOULD decide for an action, without recording anything.', {
+        action: z.string(),
+        params: z.record(z.unknown()).optional(),
+        policy: z.string().optional(),
+    }, async (args) => {
+        const r = await checkPolicy(cb, args);
+        return { content: [{ type: 'text', text: r.text }], isError: r.isError, structuredContent: r.structured };
+    });
+    server.tool('get_ledger', 'Recent entries from the tamper-evident attestation ledger (signed decisions), newest first.', { limit: z.number().int().positive().max(200).optional() }, async (args) => {
+        const r = await getLedger(cb, args);
+        return { content: [{ type: 'text', text: r.text }], isError: r.isError, structuredContent: r.structured };
+    });
+    await server.connect(new StdioServerTransport());
+}
+main().catch((err) => {
+    console.error('clearedby-mcp fatal:', err);
+    process.exit(1);
+});

package/dist/tools.d.ts

@@ -0,0 +1,23 @@
+import type { ClearedBy } from '@clearedby/sdk';
+export interface ToolResult {
+    text: string;
+    isError?: boolean;
+    structured: Record<string, unknown>;
+}
+/** request_clearance: gate the action; if held, wait for a human (≤10 min). */
+export declare function requestClearance(cb: ClearedBy, args: {
+    action: string;
+    params?: Record<string, unknown>;
+    policy?: string;
+    summary?: string;
+}): Promise<ToolResult>;
+/** check_policy: dry-run — what would the policy do, with nothing persisted. */
+export declare function checkPolicy(cb: ClearedBy, args: {
+    action: string;
+    params?: Record<string, unknown>;
+    policy?: string;
+}): Promise<ToolResult>;
+/** get_ledger: recent signed attestations. */
+export declare function getLedger(cb: ClearedBy, args: {
+    limit?: number;
+}): Promise<ToolResult>;

package/dist/tools.js

@@ -0,0 +1,73 @@
+// Tool logic for the ClearedBy MCP server (CLE-20), kept pure + framework-free
+// so it's unit-testable. Each returns { text, cleared?, result } which index.ts
+// maps to MCP content. Built on @clearedby/sdk.
+import { RejectedError } from '@clearedby/sdk';
+const hash8 = (h) => (h ? ` · attestation ${h.slice(0, 8)}` : '');
+/** request_clearance: gate the action; if held, wait for a human (≤10 min). */
+export async function requestClearance(cb, args) {
+    try {
+        const r = await cb.gate({
+            action: args.action,
+            params: args.params ?? {},
+            ...(args.policy ? { policy: args.policy } : {}),
+            ...(args.summary ? { context: { summary: args.summary } } : {}),
+        });
+        if (r.shadow) {
+            return { text: `Shadow mode — not blocking. Would have been: ${r.would?.verdict ?? 'n/a'}.`, structured: { cleared: true, shadow: true, result: r } };
+        }
+        if (r.status === 'cleared') {
+            return { text: `✅ Cleared${hash8(r.attestation?.hash)}. Safe to proceed.`, structured: { cleared: true, result: r } };
+        }
+        if (r.status === 'rejected') {
+            return { text: `⛔ Rejected${r.reason ? `: ${r.reason}` : ''}. Do NOT proceed.`, isError: false, structured: { cleared: false, reason: r.reason ?? null, result: r } };
+        }
+        // pending → a human must decide. Sync-wait up to a configurable window
+        // (CLEAREDBY_MCP_WAIT_MS, default 10 min). For long / out-of-hours waits
+        // prefer a callback_url (park-and-resume) over holding this call open
+        // (CLE-99) — the item stays open either way; only the wait differs.
+        const waitMs = Number(process.env.CLEAREDBY_MCP_WAIT_MS) || 10 * 60_000;
+        let settled;
+        try {
+            settled = await cb.wait(r.id, { timeoutMs: waitMs });
+        }
+        catch {
+            // Timed out while still pending — NOT a rejection. The item stays open
+            // for a human; surface that honestly rather than as a failure.
+            return {
+                text: `⏳ Still awaiting a human after ${Math.round(waitMs / 60000)} min — request ${r.id} stays open (not rejected). Re-check later, or pass a callback_url to be notified when it's decided.`,
+                structured: { cleared: false, pending: true, id: r.id, result: r },
+            };
+        }
+        if (settled.status === 'cleared') {
+            return { text: `✅ Approved by a reviewer${hash8(settled.attestation?.hash)}. Safe to proceed.`, structured: { cleared: true, result: settled } };
+        }
+        return { text: `⛔ Rejected by a reviewer${settled.reason ? `: ${settled.reason}` : ''}. Do NOT proceed.`, structured: { cleared: false, reason: settled.reason ?? null, result: settled } };
+    }
+    catch (err) {
+        if (err instanceof RejectedError) {
+            return { text: `⛔ Rejected: ${err.result.reason ?? 'no reason given'}. Do NOT proceed.`, structured: { cleared: false, result: err.result } };
+        }
+        return { text: `Clearance check failed: ${err instanceof Error ? err.message : 'unknown error'}`, isError: true, structured: { cleared: false } };
+    }
+}
+/** check_policy: dry-run — what would the policy do, with nothing persisted. */
+export async function checkPolicy(cb, args) {
+    try {
+        const r = await cb.check({ action: args.action, params: args.params ?? {}, ...(args.policy ? { policy: args.policy } : {}) });
+        return { text: `Dry run: would be **${r.verdict}** (rule: ${r.rule}). Nothing was recorded.`, structured: { ...r } };
+    }
+    catch (err) {
+        return { text: `Policy check failed: ${err instanceof Error ? err.message : 'unknown error'}`, isError: true, structured: {} };
+    }
+}
+/** get_ledger: recent signed attestations. */
+export async function getLedger(cb, args) {
+    try {
+        const r = await cb.ledger({ limit: args.limit ?? 20 });
+        const n = Array.isArray(r.entries) ? r.entries.length : 0;
+        return { text: `${n} recent attestation${n === 1 ? '' : 's'} (newest first).`, structured: { ...r } };
+    }
+    catch (err) {
+        return { text: `Ledger fetch failed: ${err instanceof Error ? err.message : 'unknown error'}`, isError: true, structured: {} };
+    }
+}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@clearedby/mcp",
+  "version": "0.0.1",
+  "description": "ClearedBy MCP server — request_clearance, check_policy, get_ledger from any MCP client.",
+  "license": "MIT",
+  "homepage": "https://clearedby.com",
+  "type": "module",
+  "main": "./dist/index.js",
+  "bin": {
+    "clearedby-mcp": "./dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "clearedby",
+    "approval",
+    "human-in-the-loop",
+    "ai-agents"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nl80/clearedby.git",
+    "directory": "packages/mcp"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "zod": "^3.24.1",
+    "@clearedby/sdk": "0.0.1"
+  },
+  "devDependencies": {
+    "@types/node": "^20.19.43",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "types": "./dist/index.d.ts"
+}