provenance-mcp 0.1.1

package/README.md

@@ -0,0 +1,55 @@
+# provenance-mcp
+
+**Check the wash-traffic risk of Algorand x402 endpoints before your agent pays them.**
+
+Roughly half of x402 "agentic payment" activity is artificial — self-dealing loops,
+fresh-wallet farms, metronomic bots. Provenance reads the chain and tells your agent
+whether an endpoint's revenue is **organic or fabricated**, so it can decide *before*
+sending USDC.
+
+## Tools
+
+- **`check_endpoint_risk(address)`** — free quick verdict for any Algorand endpoint
+  payTo address: risk level (`low/medium/high/critical`), 0–100 score, and the
+  on-chain red flags (distinct-payer count, self-dealing payout loops, wallet ages,
+  timing regularity, funding concentration).
+- **`provenance_service_info()`** — service + paid-tier info.
+
+Deep forensics are x402-paid on the same API: `/score` $0.05 · `/report` $0.50
+(full 8-signal grade + facilitator drift) · `/diligence` $5.00.
+
+## Install
+
+**Claude Code**
+```bash
+claude mcp add provenance -- npx -y github:apeirontrade/provenance-mcp
+```
+
+**Claude Desktop / any MCP client** (`mcpServers` config):
+```json
+{
+  "mcpServers": {
+    "provenance": {
+      "command": "npx",
+      "args": ["-y", "github:apeirontrade/provenance-mcp"]
+    }
+  }
+}
+```
+
+Then ask your agent: *“check the wash risk of Algorand endpoint \<ADDRESS\>”*.
+
+## How it works
+
+The hosted Provenance engine indexes USDC (ASA 31566704) payments on Algorand
+mainnet, enriches payer wallets (age, first funder, asset diversity, rekey
+auth-addr), clusters them (union-find over funding + shared-key links), and runs
+8 wash-detection signals. Scores are point-in-time snapshots, anchored on-chain
+for tamper-evidence. Methodology: signals, not accusations — a high score means
+the revenue pattern is consistent with self-dealing, not that the operator is
+guilty of anything.
+
+- Env: `PROVENANCE_API_URL` to point at a different Provenance deployment.
+- Free tier: 30 checks/hour/IP.
+
+MIT · Provenance — the trust layer for machine-payable endpoints.

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "provenance-mcp",
+  "version": "0.1.1",
+  "description": "MCP server that checks the wash-traffic / organic-revenue risk of Algorand x402 endpoints before your agent trusts or pays them. Free quick checks; paid deep reports via x402.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "provenance-mcp": "src/index.js"
+  },
+  "files": [
+    "src"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "mcp",
+    "modelcontextprotocol",
+    "x402",
+    "algorand",
+    "agentic-payments",
+    "wash-trading",
+    "trust",
+    "reputation"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/apeirontrade/provenance-mcp"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^3.24.1"
+  },
+  "mcpName": "io.github.apeirontrade/provenance-mcp"
+}

package/src/index.js

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+/**
+ * Provenance MCP server (public thin client).
+ *
+ * Checks the wash-traffic / organic-revenue risk of an Algorand x402 endpoint
+ * BEFORE your agent trusts or pays it — via the hosted Provenance API. The
+ * quick check is free (rate-limited); deep 8-signal reports are x402-paid.
+ *
+ * Config: PROVENANCE_API_URL (defaults to the hosted service).
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+
+const API = (process.env.PROVENANCE_API_URL ?? "https://provenance.q3epzs69b902a.us-west-2.cs.amazonlightsail.com").replace(/\/$/, "");
+const ADDR_RE = /^[A-Z2-7]{58}$/;
+
+const server = new McpServer({ name: "provenance", version: "0.1.0" });
+
+server.tool(
+  "check_endpoint_risk",
+  "Check the wash-traffic / organic-revenue risk of an Algorand x402 endpoint before trusting or paying it. Returns a risk level (low/medium/high/critical), a 0-100 score, and the specific on-chain red flags (few distinct payers, self-dealing payout loops, freshly-created wallets, metronomic timing). Free quick check via the hosted Provenance API.",
+  { address: z.string().describe("The Algorand endpoint payTo address (58 characters, A-Z and 2-7)") },
+  async ({ address }) => {
+    if (!ADDR_RE.test(address)) {
+      return { content: [{ type: "text", text: "Invalid Algorand address (expected 58 chars, A-Z2-7)." }], isError: true };
+    }
+    try {
+      const res = await fetch(`${API}/check/${address}`, { signal: AbortSignal.timeout(120_000) });
+      const body = await res.text();
+      if (!res.ok) {
+        return { content: [{ type: "text", text: `Provenance API ${res.status}: ${body.slice(0, 300)}` }], isError: true };
+      }
+      return { content: [{ type: "text", text: body }] };
+    } catch (e) {
+      return { content: [{ type: "text", text: `Could not reach the Provenance API: ${e.message}` }], isError: true };
+    }
+  },
+);
+
+server.tool(
+  "provenance_service_info",
+  "Get Provenance service info: what it rates, the free tier, and the paid x402 tiers (score $0.05, full report $0.50, deep diligence $5.00) for deeper endpoint forensics.",
+  {},
+  async () => {
+    try {
+      const res = await fetch(`${API}/`, { signal: AbortSignal.timeout(30_000) });
+      return { content: [{ type: "text", text: await res.text() }] };
+    } catch (e) {
+      return { content: [{ type: "text", text: `Could not reach the Provenance API: ${e.message}` }], isError: true };
+    }
+  },
+);
+
+const transport = new StdioServerTransport();
+await server.connect(transport);
+console.error("provenance-mcp ready (stdio) →", API);