@purposebot/mcp 0.1.0 → 0.1.2

package/README.md

@@ -1,20 +1,26 @@
 # @purposebot/mcp
 
-A thin **stdio MCP server** that proxies to the hosted PurposeBot MCP
-(`https://purposebot.ai/mcp`). Use it to plug PurposeBot — agent-native discovery,
-commerce, API Trust, and trust/reputation tools — into any MCP client (Claude
-Desktop, Cursor, Claude Code, etc.) via `npx`, without writing a custom HTTP
-integration.
+PurposeBot is an agent trust layer for the next web: agents and businesses can
+register identity, prove provenance, discover counterparties by earned trust,
+ask for API access decisions, transact through commerce workflows, and build
+reputation from verified interaction evidence.
+
+This package connects MCP clients (Claude Desktop, Cursor, Claude Code, etc.)
+to PurposeBot with `npx @purposebot/mcp`. It exposes the hosted PurposeBot MCP
+tools for trust-ranked discovery, API Trust provider registration, API access
+decisions, signed conduct events, pending feedback, commerce recommendations,
+and interaction/settlement-backed reputation.
 
 The hosted endpoint is the source of truth for the tool catalogue, so new tools
 (`search_tools`, `submit_interaction_report`, `list_pending_feedback`,
 `recommend_listings`, `create_api_trust_provider`, `request_api_trust_decision`,
-`submit_api_trust_event`, …) appear automatically — this package just forwards
-`tools/list` and `tools/call`.
+`submit_api_trust_event`, ...) appear automatically. This package is only the
+stdio transport bridge; the trust, identity, payment, and provenance checks run
+server-side in PurposeBot.
 
 ## Usage
 
-Requires Node ≥ 18. Get an API key from your PurposeBot account.
+Requires Node >= 18. Get an API key from your PurposeBot account.
 
 ### Claude Desktop / Cursor (`mcpServers` config)
 
@@ -23,7 +29,7 @@ Requires Node ≥ 18. Get an API key from your PurposeBot account.
   "mcpServers": {
     "purposebot": {
       "command": "npx",
-      "args": ["-y", "@purposebot/mcp"],
+      "args": ["-y", "@purposebot/mcp@0.1.2"],
       "env": {
         "PURPOSEBOT_API_KEY": "pb_xxx"
       }
@@ -35,15 +41,22 @@ Requires Node ≥ 18. Get an API key from your PurposeBot account.
 ### Claude Code
 
 ```bash
-claude mcp add purposebot --env PURPOSEBOT_API_KEY=pb_xxx -- npx -y @purposebot/mcp
+claude mcp add purposebot --env PURPOSEBOT_API_KEY=pb_xxx -- npx -y @purposebot/mcp@0.1.2
 ```
 
 ## Environment
 
 | Variable | Required | Default | Notes |
 |---|---|---|---|
-| `PURPOSEBOT_API_KEY` | yes | — | sent as `X-API-Key` |
-| `PURPOSEBOT_API_URL` | no | `https://purposebot.ai` | point at a sandbox/self-host |
+| `PURPOSEBOT_API_KEY` | no | - | sent as `X-API-Key`; keyless mode supports first-key registration |
+| `PURPOSEBOT_API_URL` | no | `https://purposebot.ai` | origin only; use `https://api.purposebot.ai` or sandbox/self-host origin |
+| `PURPOSEBOT_ALLOW_CUSTOM_HOST` | no | unset | set to `1` for non-PurposeBot self-hosts |
+
+The wrapper validates the target URL before sending an API key. It only sends
+keys to PurposeBot hosts by default, allows `http://localhost` for development,
+rejects embedded credentials, and refuses HTTP redirects. Without
+`PURPOSEBOT_API_KEY`, the wrapper can still call keyless MCP tools such as
+`begin_registration`; protected tools return the hosted PurposeBot auth error.
 
 ## Develop
 

package/dist/index.js

@@ -1,32 +1,52 @@
 #!/usr/bin/env node
 /**
- * PurposeBot MCP server — a thin stdio proxy to the hosted PurposeBot MCP
- * (JSON-RPC at <API_URL>/mcp). Lets agents in Claude Desktop, Cursor, etc. use
- * PurposeBot via `npx @purposebot/mcp` without a custom HTTP integration.
+ * PurposeBot agent trust layer for MCP. Agents use this bridge to reach hosted
+ * PurposeBot tools for identity, provenance, API Trust, commerce reputation,
+ * and trust-ranked discovery from Claude Desktop, Cursor, Claude Code, etc.
  *
- * It forwards tools/list and tools/call straight through; the hosted endpoint is
- * the source of truth for the tool catalogue, so new tools appear automatically.
+ * The wrapper forwards tools/list and tools/call to the hosted MCP endpoint.
+ * PurposeBot remains the source of truth for the tool catalogue and trust
+ * checks, so new tools appear automatically.
  *
  * Env:
- *   PURPOSEBOT_API_KEY   (required) — your PurposeBot API key (sent as X-API-Key)
+ *   PURPOSEBOT_API_KEY   (optional) - your PurposeBot API key (sent as X-API-Key)
  *   PURPOSEBOT_API_URL   (optional) — defaults to https://purposebot.ai
+ *   PURPOSEBOT_ALLOW_CUSTOM_HOST (optional) — set to 1 for self-hosts
  */
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
-const API_KEY = process.env.PURPOSEBOT_API_KEY;
+const API_KEY = process.env.PURPOSEBOT_API_KEY?.trim() || undefined;
+const REQUEST_TIMEOUT_MS = 60_000;
+const MAX_DIAGNOSTIC_BYTES = 2048;
+const PURPOSEBOT_TOKEN_RE = /\bpb_[A-Za-z0-9_=-]{12,}\b/g;
+const CONTROL_CHARS_RE = /[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F]/g;
+function sanitizeDiagnostic(raw) {
+    let text = typeof raw === "string" ? raw : String(raw ?? "");
+    if (API_KEY) {
+        text = text.split(API_KEY).join("[redacted-api-key]");
+    }
+    text = text.replace(PURPOSEBOT_TOKEN_RE, "[redacted-purposebot-token]");
+    text = text.replace(CONTROL_CHARS_RE, "?");
+    return text.length > MAX_DIAGNOSTIC_BYTES
+        ? `${text.slice(0, MAX_DIAGNOSTIC_BYTES)}...`
+        : text;
+}
 function die(msg) {
     console.error(`[purposebot-mcp] ${msg}`);
     process.exit(1);
 }
-// The wrapper's trust boundary: we send X-API-Key to this host on every call, so
-// validate it before any request. Default + allowlist PurposeBot hosts; require an
-// explicit opt-in for anything else; never send the key over plain http (except
-// localhost dev); reject embedded credentials.
+// The wrapper's trust boundary: if an API key is configured, it is sent to this
+// host. Validate before any request. Default + allowlist PurposeBot hosts;
+// require an explicit opt-in for anything else; never send the key over plain
+// http (except localhost dev); reject embedded credentials.
 const ALLOWED_HOSTS = new Set([
+    "api.purposebot.ai",
+    "api-sandbox.purposebot.ai",
     "purposebot.ai",
-    "www.purposebot.ai",
+    "purposebot-api.fly.dev",
     "purposebot-api-sandbox.fly.dev",
+    "www.purposebot.ai",
 ]);
 function resolveApiBase(raw) {
     let u;
@@ -34,11 +54,14 @@ function resolveApiBase(raw) {
         u = new URL(raw);
     }
     catch {
-        die(`PURPOSEBOT_API_URL is not a valid URL: ${raw}`);
+        die(`PURPOSEBOT_API_URL is not a valid URL: ${sanitizeDiagnostic(raw)}`);
     }
     const isLocal = u.hostname === "localhost" || u.hostname === "127.0.0.1";
     if (u.username || u.password)
         die("PURPOSEBOT_API_URL must not contain embedded credentials");
+    if ((u.pathname && u.pathname !== "/") || u.search || u.hash) {
+        die("PURPOSEBOT_API_URL must be an origin only, for example https://api.purposebot.ai");
+    }
     if (u.protocol !== "https:" && !(u.protocol === "http:" && isLocal)) {
         die(`PURPOSEBOT_API_URL must use https (http allowed only for localhost), got ${u.protocol}`);
     }
@@ -48,39 +71,81 @@ function resolveApiBase(raw) {
     }
     return `${u.protocol}//${u.host}`;
 }
-if (!API_KEY) {
-    die("PURPOSEBOT_API_KEY is required. Set it in your MCP client config (env).");
-}
 const API_URL = resolveApiBase(process.env.PURPOSEBOT_API_URL ?? "https://purposebot.ai");
 const MCP_ENDPOINT = `${API_URL}/mcp`;
 let rpcId = 0;
+async function readDiagnosticBody(res) {
+    const reader = res.body?.getReader();
+    if (!reader)
+        return "";
+    const decoder = new TextDecoder();
+    let bytesRead = 0;
+    let text = "";
+    try {
+        while (bytesRead < MAX_DIAGNOSTIC_BYTES) {
+            const { done, value } = await reader.read();
+            if (done) {
+                text += decoder.decode();
+                return text;
+            }
+            const remaining = MAX_DIAGNOSTIC_BYTES - bytesRead;
+            const chunk = value.byteLength > remaining ? value.subarray(0, remaining) : value;
+            bytesRead += chunk.byteLength;
+            text += decoder.decode(chunk, { stream: true });
+            if (value.byteLength > remaining) {
+                await reader.cancel().catch(() => undefined);
+                return `${text}${decoder.decode()}...`;
+            }
+        }
+        await reader.cancel().catch(() => undefined);
+        return `${text}${decoder.decode()}...`;
+    }
+    finally {
+        reader.releaseLock();
+    }
+}
 async function rpc(method, params) {
-    const res = await fetch(MCP_ENDPOINT, {
-        method: "POST",
-        headers: {
-            "content-type": "application/json",
-            "x-api-key": API_KEY,
-        },
-        body: JSON.stringify({ jsonrpc: "2.0", id: ++rpcId, method, params }),
-        // Never follow redirects: undici keeps custom headers (X-API-Key) on
-        // cross-origin redirects, so a 30x from an allowlisted host could leak the
-        // key. Fail instead — the host allowlist only guards the INITIAL request.
-        redirect: "error",
-    });
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+    let res;
+    const headers = {
+        "content-type": "application/json",
+    };
+    if (API_KEY) {
+        headers["x-api-key"] = API_KEY;
+    }
+    try {
+        res = await fetch(MCP_ENDPOINT, {
+            method: "POST",
+            headers,
+            body: JSON.stringify({ jsonrpc: "2.0", id: ++rpcId, method, params }),
+            // Never follow redirects: undici keeps custom headers (X-API-Key) on
+            // cross-origin redirects, so a 30x from an allowlisted host could leak the
+            // key. Fail instead - the host allowlist only guards the INITIAL request.
+            redirect: "error",
+            signal: controller.signal,
+        });
+    }
+    catch (err) {
+        throw new Error(`PurposeBot MCP ${method} request failed: ${sanitizeDiagnostic(err instanceof Error ? err.message : err)}`);
+    }
+    finally {
+        clearTimeout(timeout);
+    }
     if (!res.ok) {
-        const text = await res.text().catch(() => "");
+        const text = sanitizeDiagnostic(await readDiagnosticBody(res).catch(() => ""));
         throw new Error(`PurposeBot MCP ${method} -> HTTP ${res.status}: ${text}`);
     }
     const body = (await res.json());
     if (body.error) {
-        throw new Error(`PurposeBot MCP ${method} error ${body.error.code}: ${body.error.message}`);
+        throw new Error(`PurposeBot MCP ${method} error ${body.error.code}: ${sanitizeDiagnostic(body.error.message)}`);
     }
     return body.result;
 }
-const server = new Server({ name: "purposebot", version: "0.1.0" }, { capabilities: { tools: {} } });
-server.setRequestHandler(ListToolsRequestSchema, async () => {
-    const result = await rpc("tools/list");
-    return { tools: Array.isArray(result?.tools) ? result.tools : [] };
+const server = new Server({ name: "purposebot", version: "0.1.2" }, { capabilities: { tools: {} } });
+server.setRequestHandler(ListToolsRequestSchema, async (request) => {
+    const result = await rpc("tools/list", request.params);
+    return { ...(result ?? {}), tools: Array.isArray(result?.tools) ? result.tools : [] };
 });
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const result = await rpc("tools/call", {
@@ -96,7 +161,8 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 });
 async function main() {
     await server.connect(new StdioServerTransport());
-    console.error(`[purposebot-mcp] connected — proxying ${MCP_ENDPOINT}`);
+    const authMode = API_KEY ? "authenticated" : "keyless";
+    console.error(`[purposebot-mcp] connected - proxying ${MCP_ENDPOINT} (${authMode})`);
 }
 main().catch((err) => {
     console.error("[purposebot-mcp] fatal:", err);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@purposebot/mcp",
-  "version": "0.1.0",
-  "description": "PurposeBot MCP server — stdio proxy to the hosted PurposeBot MCP (https://purposebot.ai/mcp) so agents in Claude Desktop, Cursor, etc. can use it via npx.",
+  "version": "0.1.2",
+  "description": "PurposeBot agent trust layer for MCP: agent identity, provenance, API access decisions, commerce reputation, and trust-ranked discovery.",
   "type": "module",
   "bin": {
     "purposebot-mcp": "dist/index.js"
@@ -22,12 +22,17 @@
     "mcp",
     "model-context-protocol",
     "purposebot",
+    "agent-trust",
+    "agent-identity",
+    "api-trust",
+    "provenance",
+    "reputation",
     "agent-commerce",
-    "trust"
+    "discovery"
   ],
   "license": "MIT",
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.0.0"
+    "@modelcontextprotocol/sdk": "1.29.0"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",