@kaditang/402sentinel-mcp 0.1.0 → 0.3.0

package/README.md

@@ -1,10 +1,21 @@
 # 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.
+MCP tools that let your AI agent **check an x402 counterparty's risk before it
+pays** — and turn that risk into an enforceable wallet spending policy. 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) + a delivery-outcome
+flywheel, with honest confidence/coverage.
+
+Tools — vet the **seller**:
+- `assess_counterparty` ($0.002) — risk score + decision + a ready-to-apply `recommended_policy`
+- `assess_counterparty_deep` ($0.02) — same, scans more on-chain history
+- `recommend_policy` ($0.002) — decision + wallet-ready spending policy (caps, denylist, approval)
+- `report_outcome` (free) — after paying, report delivery to train the reliability flywheel
+
+Tools — vet the **payment itself** (buyer-side):
+- `firewall` ($0.002) — should YOUR agent make THIS payment now? Catches fraudulent routing (payTo swapped vs the address you usually pay), drain velocity, overcharge, and injection-sourced instructions. Pass your payer wallet as `agent_id`.
+- `firewall_record` (free) — seed your agent's payment history so the firewall has a behavioural baseline.
 
 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
@@ -33,8 +44,9 @@ Add to your MCP client (Claude Desktop, Cursor, etc.):
 }
 ```
 
-Each assessment costs **$0.01**, paid automatically in USDC via x402 (Circle
-Gateway, gas-free on Base) from the configured wallet.
+Paid calls cost from **$0.002** (shallow) to **$0.02** (deep), paid automatically
+in USDC via x402 (Circle Gateway, gas-free on Base) from the configured wallet.
+`report_outcome` is free. (`CLIENT_PRIVATE_KEY` is only needed for the paid tools.)
 
 ## Use
 
@@ -46,13 +58,21 @@ assess_counterparty({
   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: "..." }
+→ { decision: "review", risk_score: 52, confidence: 0.41, coverage: {...},
+    dimensions: [...], recommendation: "...",
+    recommended_policy: { action: "limit", max_payment_usdc: 5, daily_cap_usdc: 15,
+                          add_to_denylist: false, require_human_approval: true } }
 ```
 
-- `block` → don't pay
-- `review` → cap exposure / escrow
+- `block` / `deny` → don't pay
+- `review` / `limit` → cap exposure / escrow (use `recommended_policy` for the caps)
 - `allow` → proceed
 
+`recommend_policy(...)` returns just the decision + `recommended_policy` — apply
+`max_payment_usdc` / `daily_cap_usdc` / `add_to_denylist` directly to your agent
+wallet's spending limits. After paying, call `report_outcome({ assessment_id,
+outcome })` to improve future scores.
+
 ## Disclaimer
 
 Algorithmic risk signal, informational only — **not advice, not an endorsement,

package/dist/index.js

@@ -2,15 +2,22 @@
 /**
  * 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.
+ * Tools an agent calls around an x402 payment:
+ *   - assess_counterparty       ($0.002) — risk score + allow/review/block + a
+ *                                          ready-to-apply spending policy
+ *   - assess_counterparty_deep  ($0.02)  — same, deeper on-chain history
+ *   - recommend_policy          ($0.002) — trimmed view: decision + wallet-ready
+ *                                          spending policy (caps, denylist, approval)
+ *   - report_outcome            (FREE)   — after paying, report delivery to train
+ *                                          the settlement-reliability flywheel
+ *
+ * Payments settle via x402 (Circle Gateway on Base). The scoring model /
+ * facilitator logic / flywheel 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.
+ *   CLIENT_PRIVATE_KEY  — a Base wallet with USDC in its Circle Gateway balance.
+ *                         Required for the paid tools (not for report_outcome).
  *   SENTINEL_URL        — override base URL (default https://402sentinel.com).
  */
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
@@ -19,41 +26,154 @@ import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextpro
 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 targetSchema = {
+    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)" },
+    },
+};
+const paymentContextSchema = {
+    type: "object",
+    properties: {
+        amount: { type: "number", description: "Payment amount you're about to make" },
+        asset: { type: "string", description: "e.g. USDC" },
+    },
+};
+const assessInput = {
+    type: "object",
+    required: ["target"],
+    properties: {
+        target: targetSchema,
+        payment_context: paymentContextSchema,
+        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)" },
+            },
+        },
+    },
+};
+const policyInput = {
+    type: "object",
+    required: ["target"],
+    properties: {
+        target: targetSchema,
+        payment_context: paymentContextSchema,
+        policy: {
+            type: "object",
+            properties: {
+                max_payment_usdc: { type: "number", description: "most you'd expose to ONE counterparty (default 50)" },
+                review_ceiling_usdc: { type: "number", description: "hard per-payment cap on the review tier (default 5)" },
+                min_confidence: { type: "number", description: "below this => require human approval (default 0.5)" },
+            },
+        },
+    },
+};
 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).",
+        description: "Assess the risk of an x402 counterparty (a payTo address) BEFORE paying. Returns a 0-100 risk_score, an allow/review/block decision, honest confidence/coverage, and a ready-to-apply recommended_policy (per-counterparty caps + approval/denylist), scored from on-chain settlement behaviour on Base + a delivery-outcome flywheel. Call before authorizing any x402 payment above your risk threshold. Costs $0.002 (paid automatically in USDC).",
+        inputSchema: assessInput,
+        endpoint: "/api/assess",
+        paid: true,
+    },
+    {
+        name: "assess_counterparty_deep",
+        description: "Like assess_counterparty but scans more on-chain settlement history for a higher-confidence read. Use for larger or higher-stakes payments. Costs $0.02 (paid automatically in USDC).",
+        inputSchema: assessInput,
+        endpoint: "/api/assess/deep",
+        paid: true,
+    },
+    {
+        name: "recommend_policy",
+        description: "Turn a counterparty's risk into an enforceable spending policy you can apply to your agent wallet. Returns an allow/limit/deny decision plus recommended_policy: max_payment_usdc (per-counterparty cap), daily_cap_usdc, add_to_denylist, require_human_approval. Costs $0.002 (paid automatically in USDC).",
+        inputSchema: policyInput,
+        endpoint: "/api/policy",
+        paid: true,
+    },
+    {
+        name: "report_outcome",
+        description: "FREE. After you pay a counterparty, report whether they delivered so 402Sentinel's settlement-reliability flywheel can learn. Pass the assessment_id returned by a prior assessment.",
+        inputSchema: {
+            type: "object",
+            required: ["assessment_id", "outcome"],
+            properties: {
+                assessment_id: { type: "string", description: "assessment_id from a prior assess/policy call" },
+                outcome: { type: "string", enum: ["delivered", "partial", "not_delivered", "overcharged"] },
+                tx_hash: { type: "string", description: "settlement tx hash (optional)" },
+            },
+        },
+        endpoint: "/api/report_outcome",
+        paid: false,
+    },
+    {
+        name: "firewall",
+        description: "Buyer-side payment firewall: should YOUR agent make THIS payment now? Where assess_counterparty vets the seller, this vets the payment instruction in the context of your agent's own history + provenance. Returns allow/hold/block + signals: routing_anomaly (payTo swapped vs the address you usually pay for this resource = fraudulent routing), velocity_anomaly (drain), amount_anomaly (overcharge), provenance_flag (injection/untrusted source), counterparty_risk. Pass your payer wallet as agent_id. Costs $0.002. Seed history free with firewall_record.",
         inputSchema: {
             type: "object",
-            required: ["target"],
+            required: ["agent_id", "payment"],
             properties: {
-                target: {
+                agent_id: { type: "string", description: "stable id for your agent — use your payer wallet address" },
+                payment: {
                     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)" },
+                        payto_address: { type: "string", description: "address you're about to pay" },
+                        amount: { type: "number" },
+                        asset: { type: "string", description: "e.g. USDC" },
+                        resource_url: { type: "string", description: "what you're paying for" },
                     },
                 },
-                payment_context: {
+                context: {
                     type: "object",
                     properties: {
-                        amount: { type: "number", description: "Payment amount you're about to make" },
-                        asset: { type: "string", description: "e.g. USDC" },
+                        source: { type: "string", enum: ["tool_output", "web_content", "user", "unknown"], description: "where the payTo/instruction came from" },
+                        metadata: { type: "object", description: "x402 description/reason strings (scanned for injection)" },
+                        expected_payto: { type: "string", description: "known-good address for this resource (optional)" },
                     },
                 },
                 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)" },
+                        max_payment_usdc: { type: "number" },
+                        velocity_window_min: { type: "number" },
+                        velocity_cap_usdc: { type: "number" },
+                        check_counterparty: { type: "boolean" },
+                        block_on: { type: "array", items: { type: "string" } },
+                    },
+                },
+            },
+        },
+        endpoint: "/api/firewall",
+        paid: true,
+    },
+    {
+        name: "firewall_record",
+        description: "FREE. Seed your agent's payment history so the firewall has a behavioural baseline (record past/known-good payments). Pass your payer wallet as agent_id.",
+        inputSchema: {
+            type: "object",
+            required: ["agent_id", "payment"],
+            properties: {
+                agent_id: { type: "string", description: "use your payer wallet address" },
+                payment: {
+                    type: "object",
+                    required: ["payto_address"],
+                    properties: {
+                        payto_address: { type: "string" },
+                        amount: { type: "number" },
+                        asset: { type: "string" },
+                        resource_url: { type: "string" },
                     },
                 },
-                depth: { type: "string", enum: ["shallow", "deep"], description: "shallow=cheap/cached, deep=fresh (default shallow)" },
             },
         },
+        endpoint: "/api/firewall/record",
+        paid: false,
     },
 ];
 function clientOrNull() {
@@ -63,35 +183,47 @@ function clientOrNull() {
     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 }));
+    const server = new Server({ name: "402sentinel", version: "0.3.0" }, { capabilities: { tools: {} } });
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({
+        tools: TOOLS.map(({ name, description, inputSchema }) => ({ name, description, inputSchema })),
+    }));
     server.setRequestHandler(CallToolRequestSchema, async (req) => {
         const { name, arguments: args } = req.params;
-        if (name !== "assess_counterparty") {
+        const tool = TOOLS.find((t) => t.name === name);
+        if (!tool) {
             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,
-            });
+            let data;
+            if (tool.paid) {
+                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 for the call.",
+                                }),
+                            }],
+                        isError: true,
+                    };
+                }
+                ({ data } = await client.pay(`${BASE}${tool.endpoint}`, { method: "POST", body: args }));
+            }
+            else {
+                // free endpoint — plain POST, no payment
+                const res = await fetch(`${BASE}${tool.endpoint}`, {
+                    method: "POST",
+                    headers: { "Content-Type": "application/json" },
+                    body: JSON.stringify(args ?? {}),
+                });
+                data = await res.json().catch(() => ({}));
+            }
             return { content: [{ type: "text", text: JSON.stringify(data) }] };
         }
         catch (e) {
             return {
-                content: [{ type: "text", text: JSON.stringify({ error: `assessment failed: ${e.message}` }) }],
+                content: [{ type: "text", text: JSON.stringify({ error: `${name} failed: ${e.message}` }) }],
                 isError: true,
             };
         }

package/package.json

@@ -1,7 +1,7 @@
 {
   "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.",
+  "version": "0.3.0",
+  "description": "MCP tools for x402 payment safety — vet the counterparty (risk score, allow/review/block, spending policy) AND vet the payment itself (buyer-side firewall: routing/drain/injection). Thin client for 402sentinel.com.",
   "type": "module",
   "bin": { "402sentinel-mcp": "./dist/index.js" },
   "main": "dist/index.js",