@kaditang/402sentinel-mcp 0.1.0

package/README.md

@@ -0,0 +1,64 @@
+# 402sentinel-mcp
+
+An MCP tool that lets your AI agent **check an x402 counterparty's risk before it
+pays**. One tool, `assess_counterparty`: give it a payTo address, get back a
+0–100 risk score + an `allow` / `review` / `block` decision, scored from on-chain
+settlement behaviour on Base (address age, facilitator-aware payer diversity,
+settlement maturity) with honest confidence/coverage.
+
+It's a thin client for the hosted service at **https://402sentinel.com** — the
+scoring model and facilitator-identification logic live server-side (closed); this
+package only forwards the request and pays for it, so it's open source.
+
+## Install
+
+```sh
+npm i -g @kaditang/402sentinel-mcp
+```
+
+## Configure
+
+Add to your MCP client (Claude Desktop, Cursor, etc.):
+
+```jsonc
+{
+  "mcpServers": {
+    "402sentinel": {
+      "command": "402sentinel-mcp",
+      "env": {
+        "CLIENT_PRIVATE_KEY": "0x...  // a Base wallet with USDC in its Circle Gateway balance"
+      }
+    }
+  }
+}
+```
+
+Each assessment costs **$0.01**, paid automatically in USDC via x402 (Circle
+Gateway, gas-free on Base) from the configured wallet.
+
+## Use
+
+The agent calls it before authorizing a payment:
+
+```
+assess_counterparty({
+  target: { payto_address: "0x..." },
+  payment_context: { amount: 10, asset: "USDC" },
+  policy: { block_at_score: 70, review_at_score: 40 }
+})
+→ { decision: "review", risk_score: 52, confidence: 0.41, coverage: {...}, dimensions: [...], recommendation: "..." }
+```
+
+- `block` → don't pay
+- `review` → cap exposure / escrow
+- `allow` → proceed
+
+## Disclaimer
+
+Algorithmic risk signal, informational only — **not advice, not an endorsement,
+and not an accusation** about any party. Scores are probabilistic estimates from
+limited public on-chain data and heuristics, and may misclassify. Do your own due
+diligence; don't rely on it as your sole basis to pay or refuse. See
+https://402sentinel.com/terms.
+
+MIT.

package/dist/index.js

@@ -0,0 +1,105 @@
+#!/usr/bin/env node
+/**
+ * 402Sentinel MCP — thin, open-source client.
+ *
+ * Exposes one tool, `assess_counterparty`, that an agent calls BEFORE paying an
+ * x402 counterparty. It pays $0.01 (x402, Circle Gateway on Base) to the hosted
+ * 402sentinel.com scoring service and returns a 0-100 risk score + allow/review/
+ * block decision. The scoring model / facilitator logic live server-side
+ * (closed); this client only forwards + pays, so it's safe to open-source.
+ *
+ * Config (env):
+ *   CLIENT_PRIVATE_KEY  — a Base wallet with USDC in its Circle Gateway balance
+ *                         (it pays $0.01 per assessment). Required.
+ *   SENTINEL_URL        — override base URL (default https://402sentinel.com).
+ */
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { GatewayClient } from "@circle-fin/x402-batching/client";
+const BASE = (process.env.SENTINEL_URL ?? "https://402sentinel.com").replace(/\/$/, "");
+const RAW_PK = process.env.CLIENT_PRIVATE_KEY ?? "";
+const TOOLS = [
+    {
+        name: "assess_counterparty",
+        description: "Assess the risk of an x402 counterparty (a payTo address) BEFORE paying. Returns a 0-100 risk_score and an allow/review/block decision relative to your policy, scored from on-chain settlement behaviour on Base (address age, facilitator-aware payer diversity, settlement maturity) with honest confidence/coverage. Call this before authorizing any x402 payment above your risk threshold. Costs $0.01 (paid automatically in USDC).",
+        inputSchema: {
+            type: "object",
+            required: ["target"],
+            properties: {
+                target: {
+                    type: "object",
+                    required: ["payto_address"],
+                    properties: {
+                        payto_address: { type: "string", description: "Chain address that will receive the payment" },
+                        resource_url: { type: "string", description: "The x402 resource/endpoint URL (optional)" },
+                        network: { type: "string", description: "CAIP-2 chain id, e.g. eip155:8453 (optional)" },
+                    },
+                },
+                payment_context: {
+                    type: "object",
+                    properties: {
+                        amount: { type: "number", description: "Payment amount you're about to make" },
+                        asset: { type: "string", description: "e.g. USDC" },
+                    },
+                },
+                policy: {
+                    type: "object",
+                    properties: {
+                        block_at_score: { type: "number", description: "risk >= this => block (default 70)" },
+                        review_at_score: { type: "number", description: "risk >= this => review (default 40)" },
+                        min_confidence: { type: "number", description: "below this => force review (default 0.5)" },
+                    },
+                },
+                depth: { type: "string", enum: ["shallow", "deep"], description: "shallow=cheap/cached, deep=fresh (default shallow)" },
+            },
+        },
+    },
+];
+function clientOrNull() {
+    if (!RAW_PK || RAW_PK.startsWith("0xYour"))
+        return null;
+    const pk = (RAW_PK.startsWith("0x") ? RAW_PK : `0x${RAW_PK}`);
+    return new GatewayClient({ chain: "base", privateKey: pk });
+}
+async function main() {
+    const server = new Server({ name: "402sentinel", version: "0.1.0" }, { capabilities: { tools: {} } });
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
+    server.setRequestHandler(CallToolRequestSchema, async (req) => {
+        const { name, arguments: args } = req.params;
+        if (name !== "assess_counterparty") {
+            return { content: [{ type: "text", text: `unknown tool: ${name}` }], isError: true };
+        }
+        const client = clientOrNull();
+        if (!client) {
+            return {
+                content: [{
+                        type: "text",
+                        text: JSON.stringify({
+                            error: "CLIENT_PRIVATE_KEY not set. Provide a Base wallet (with USDC in its Circle Gateway balance) so this tool can pay $0.01 per assessment.",
+                        }),
+                    }],
+                isError: true,
+            };
+        }
+        try {
+            const { data } = await client.pay(`${BASE}/api/assess`, {
+                method: "POST",
+                body: args,
+            });
+            return { content: [{ type: "text", text: JSON.stringify(data) }] };
+        }
+        catch (e) {
+            return {
+                content: [{ type: "text", text: JSON.stringify({ error: `assessment failed: ${e.message}` }) }],
+                isError: true,
+            };
+        }
+    });
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((e) => {
+    console.error("402sentinel-mcp fatal:", e);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@kaditang/402sentinel-mcp",
+  "version": "0.1.0",
+  "description": "MCP tool to assess an x402 counterparty's risk BEFORE paying — allow/review/block, scored on-chain. Thin client for 402sentinel.com.",
+  "type": "module",
+  "bin": { "402sentinel-mcp": "./dist/index.js" },
+  "main": "dist/index.js",
+  "files": ["dist", "README.md"],
+  "scripts": {
+    "build": "node node_modules/typescript/bin/tsc",
+    "start": "node dist/index.js",
+    "dev": "node node_modules/tsx/dist/cli.mjs src/index.ts",
+    "prepublishOnly": "node node_modules/typescript/bin/tsc"
+  },
+  "keywords": ["x402", "mcp", "ai-agents", "risk", "counterparty", "base", "usdc"],
+  "author": "Biao Tang",
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.4",
+    "@circle-fin/x402-batching": "^3.0.0"
+  },
+  "devDependencies": {
+    "tsx": "^4.0.0",
+    "typescript": "^5.0.0"
+  },
+  "mcpName": "io.github.kaditang/402sentinel-mcp"
+}