@purposebot/mcp 0.1.0

package/README.md

@@ -0,0 +1,58 @@
+# @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.
+
+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`.
+
+## Usage
+
+Requires Node ≥ 18. Get an API key from your PurposeBot account.
+
+### Claude Desktop / Cursor (`mcpServers` config)
+
+```json
+{
+  "mcpServers": {
+    "purposebot": {
+      "command": "npx",
+      "args": ["-y", "@purposebot/mcp"],
+      "env": {
+        "PURPOSEBOT_API_KEY": "pb_xxx"
+      }
+    }
+  }
+}
+```
+
+### Claude Code
+
+```bash
+claude mcp add purposebot --env PURPOSEBOT_API_KEY=pb_xxx -- npx -y @purposebot/mcp
+```
+
+## 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 |
+
+## Develop
+
+```bash
+npm install
+npm run build     # tsc -> dist/
+PURPOSEBOT_API_KEY=pb_xxx node dist/index.js   # runs the stdio server
+```
+
+The server is a transparent proxy: auth is the PurposeBot API key, and write/
+trust-signal tools still enforce their own provenance and signed-proof
+requirements server-side.

package/dist/index.js

@@ -0,0 +1,104 @@
+#!/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.
+ *
+ * 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.
+ *
+ * Env:
+ *   PURPOSEBOT_API_KEY   (required) — your PurposeBot API key (sent as X-API-Key)
+ *   PURPOSEBOT_API_URL   (optional) — defaults to https://purposebot.ai
+ */
+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;
+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.
+const ALLOWED_HOSTS = new Set([
+    "purposebot.ai",
+    "www.purposebot.ai",
+    "purposebot-api-sandbox.fly.dev",
+]);
+function resolveApiBase(raw) {
+    let u;
+    try {
+        u = new URL(raw);
+    }
+    catch {
+        die(`PURPOSEBOT_API_URL is not a valid URL: ${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.protocol !== "https:" && !(u.protocol === "http:" && isLocal)) {
+        die(`PURPOSEBOT_API_URL must use https (http allowed only for localhost), got ${u.protocol}`);
+    }
+    if (!ALLOWED_HOSTS.has(u.hostname) && !isLocal && process.env.PURPOSEBOT_ALLOW_CUSTOM_HOST !== "1") {
+        die(`refusing to send your API key to non-PurposeBot host "${u.hostname}". ` +
+            `If this is intentional (self-host/sandbox), set PURPOSEBOT_ALLOW_CUSTOM_HOST=1.`);
+    }
+    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 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",
+    });
+    if (!res.ok) {
+        const text = await res.text().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}`);
+    }
+    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 : [] };
+});
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const result = await rpc("tools/call", {
+        name: request.params.name,
+        arguments: request.params.arguments ?? {},
+    });
+    // The hosted endpoint already returns MCP-shaped { content, isError }; pass it
+    // through. Fall back to wrapping a raw result as text for forward-compat.
+    if (result && Array.isArray(result.content)) {
+        return result;
+    }
+    return { content: [{ type: "text", text: JSON.stringify(result ?? {}, null, 2) }] };
+});
+async function main() {
+    await server.connect(new StdioServerTransport());
+    console.error(`[purposebot-mcp] connected — proxying ${MCP_ENDPOINT}`);
+}
+main().catch((err) => {
+    console.error("[purposebot-mcp] fatal:", err);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,36 @@
+{
+  "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.",
+  "type": "module",
+  "bin": {
+    "purposebot-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "purposebot",
+    "agent-commerce",
+    "trust"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.4.0"
+  }
+}