frisk-mcp 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Frisk contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,102 @@
+# frisk-mcp
+
+An [MCP](https://modelcontextprotocol.io) server for [Frisk](https://github.com/Jiangw2718i/frisk):
+screen the counterparty of an x402 payment before an agent pays it.
+
+It exposes one tool, `screen_payment`, which runs Frisk's deterministic checks —
+address sanity, dynamic-`payTo` comparison, transport safety, and your own
+spending policy — and returns `allow` / `review` / `block` with reasons.
+
+## Where this belongs, and where it does not
+
+An MCP tool runs when a model decides to call it. A payment check that the model
+can skip is a weaker guarantee than the same check on the code path that signs
+the payment.
+
+So:
+
+- **Use the library** — [`frisk-screen`](https://www.npmjs.com/package/frisk-screen) —
+  where the money actually moves. It is MIT, dependency-free, and runs locally.
+- **Use this server** for inspection ("is this address safe to pay?"), and for
+  agents that cannot import a library.
+
+Frisk is advisory in both cases: it returns a verdict and your code decides. It
+never holds funds and cannot stop a payment by itself.
+
+## Install
+
+```bash
+npx frisk-mcp
+```
+
+In any MCP client's server configuration:
+
+```json
+{
+  "mcpServers": {
+    "frisk": {
+      "command": "npx",
+      "args": ["-y", "frisk-mcp"]
+    }
+  }
+}
+```
+
+No API key, no account, no network call: with no configuration the server
+screens entirely on your machine.
+
+## Hosted mode (optional)
+
+Set `FRISK_API_KEY` to have the same tool answered by the hosted service, which
+adds reputation-graph signals and returns higher-confidence verdicts:
+
+```json
+{
+  "mcpServers": {
+    "frisk": {
+      "command": "npx",
+      "args": ["-y", "frisk-mcp"],
+      "env": { "FRISK_API_KEY": "..." }
+    }
+  }
+}
+```
+
+The hosted tier is in early access — email support@tryfrisk.dev. Everything
+above works without it.
+
+| variable | default | meaning |
+| --- | --- | --- |
+| `FRISK_API_KEY` | unset | Enables hosted screening. Unset means fully offline. |
+| `FRISK_BASE_URL` | `https://api.tryfrisk.dev` | Override the hosted endpoint. |
+
+## The tool
+
+`screen_payment`
+
+| argument | type | notes |
+| --- | --- | --- |
+| `counterparty` | string, required | The address the agent intends to pay. |
+| `endpoint` | string | URL that quoted the payment; checked for plaintext transport. |
+| `amount` | number | Amount about to be paid. |
+| `asset` | string | Asset symbol, e.g. `USDC`. |
+| `observedPayTo` | string | The `payTo` the endpoint actually returned. If it differs from `counterparty`, that is the dynamic-`payTo` swap. |
+| `strictness` | number 0–1 | 0 permissive, 1 paranoid. Default 0.3. |
+| `maxPerCall` | number | Spending ceiling for one call. |
+| `allowedAssets` | string[] | Assets the agent may pay in. |
+
+Returns `verdict`, `trustScore`, `confidence`, `reasons`, `policyHits`,
+`source` (`lite` or `hosted`), and `allowed`.
+
+## What it does not do
+
+It does not detect Sybil clusters, and offline it has no view of an address's
+history — lite screening always reports `"low"` confidence for that reason. It
+also cannot repair the protocol underneath a payment: replay, settlement races,
+and facilitator trust live in x402 itself, not in the request being signed.
+Those limits are discussed in
+[Five ways an x402 payment can go wrong](https://tryfrisk.dev/blog/screening-x402-payments).
+
+## License
+
+MIT

package/dist/index.js

@@ -0,0 +1,94 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { StdioServerTransport } from "@modelcontextprotocol/server/stdio";
+
+// src/server.ts
+import { McpServer } from "@modelcontextprotocol/server";
+import { Client } from "frisk-screen";
+import { z } from "zod";
+var inputSchema = z.object({
+  counterparty: z.string().describe("The address the agent intends to pay, e.g. an 0x EVM address."),
+  endpoint: z.string().optional().describe("URL that quoted the payment. Used to check transport safety."),
+  amount: z.number().optional().describe("Amount the agent is about to pay."),
+  asset: z.string().optional().describe("Asset symbol, e.g. USDC."),
+  observedPayTo: z.string().optional().describe(
+    "The payTo address the endpoint actually returned for this request. If it differs from the counterparty, that is the dynamic-payTo swap."
+  ),
+  strictness: z.number().min(0).max(1).optional().describe("0 is permissive, 1 is paranoid. Defaults to 0.3."),
+  maxPerCall: z.number().optional().describe("Spending ceiling for a single call."),
+  allowedAssets: z.array(z.string()).optional().describe("Assets the agent is permitted to pay in.")
+});
+function describeResult(result) {
+  const lines = [
+    `verdict: ${result.verdict}`,
+    `trust score: ${result.trustScore}`,
+    `confidence: ${result.confidence}`,
+    `source: ${result.source}`
+  ];
+  if (result.reasons.length > 0) {
+    lines.push(`reasons: ${result.reasons.join("; ")}`);
+  }
+  if (result.policyHits.length > 0) {
+    lines.push(`policy hits: ${result.policyHits.join("; ")}`);
+  }
+  return lines.join("\n");
+}
+function createServer(options = {}) {
+  const client = new Client({
+    apiKey: options.apiKey,
+    baseUrl: options.baseUrl
+  });
+  const server = new McpServer({
+    name: "frisk",
+    version: "0.0.1"
+  });
+  server.registerTool(
+    "screen_payment",
+    {
+      title: "Screen a payment before paying",
+      description: client.mode === "hosted" ? "Screen a counterparty an agent is about to pay. Runs the local deterministic checks and the hosted reputation graph, and returns allow / review / block with reasons. Advisory: the caller decides." : "Screen a counterparty an agent is about to pay. Runs entirely offline: address sanity, dynamic-payTo comparison, transport check, and your spending policy. Returns allow / review / block with reasons. Advisory: the caller decides. Set FRISK_API_KEY to add hosted reputation signals.",
+      inputSchema,
+      annotations: {
+        readOnlyHint: true,
+        openWorldHint: client.mode === "hosted"
+      }
+    },
+    async ({ counterparty, maxPerCall, allowedAssets, ...rest }) => {
+      const policy = maxPerCall === void 0 && allowedAssets === void 0 ? void 0 : { maxPerCall, allowedAssets };
+      try {
+        const result = await client.screen(counterparty, { ...rest, policy });
+        return {
+          content: [{ type: "text", text: describeResult(result) }],
+          structuredContent: { ...result }
+        };
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+          isError: true,
+          content: [
+            {
+              type: "text",
+              text: `screening failed: ${message}`
+            }
+          ]
+        };
+      }
+    }
+  );
+  return server;
+}
+
+// src/index.ts
+async function main() {
+  const server = createServer({
+    apiKey: process.env.FRISK_API_KEY,
+    baseUrl: process.env.FRISK_BASE_URL
+  });
+  await server.connect(new StdioServerTransport());
+}
+main().catch((error) => {
+  console.error(error);
+  process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/server.ts"],"sourcesContent":["import { StdioServerTransport } from \"@modelcontextprotocol/server/stdio\";\nimport { createServer } from \"./server.js\";\n\nasync function main(): Promise<void> {\n  const server = createServer({\n    apiKey: process.env.FRISK_API_KEY,\n    baseUrl: process.env.FRISK_BASE_URL,\n  });\n  await server.connect(new StdioServerTransport());\n}\n\nmain().catch((error) => {\n  // stdout carries the protocol, so diagnostics go to stderr.\n  console.error(error);\n  process.exit(1);\n});\n","import { McpServer } from \"@modelcontextprotocol/server\";\nimport { Client, type ScreenResult } from \"frisk-screen\";\nimport { z } from \"zod\";\n\nexport interface ServerOptions {\n  /** Hosted API key. Without one the server screens entirely offline. */\n  apiKey?: string;\n  /** Override the hosted base URL. Only used when an API key is supplied. */\n  baseUrl?: string;\n}\n\nconst inputSchema = z.object({\n  counterparty: z\n    .string()\n    .describe(\"The address the agent intends to pay, e.g. an 0x EVM address.\"),\n  endpoint: z\n    .string()\n    .optional()\n    .describe(\"URL that quoted the payment. Used to check transport safety.\"),\n  amount: z.number().optional().describe(\"Amount the agent is about to pay.\"),\n  asset: z.string().optional().describe(\"Asset symbol, e.g. USDC.\"),\n  observedPayTo: z\n    .string()\n    .optional()\n    .describe(\n      \"The payTo address the endpoint actually returned for this request. If it differs from the counterparty, that is the dynamic-payTo swap.\",\n    ),\n  strictness: z\n    .number()\n    .min(0)\n    .max(1)\n    .optional()\n    .describe(\"0 is permissive, 1 is paranoid. Defaults to 0.3.\"),\n  maxPerCall: z\n    .number()\n    .optional()\n    .describe(\"Spending ceiling for a single call.\"),\n  allowedAssets: z\n    .array(z.string())\n    .optional()\n    .describe(\"Assets the agent is permitted to pay in.\"),\n});\n\n/**\n * The verdict is advisory. Frisk returns a recommendation and the caller\n * decides; it never holds funds and cannot stop a payment by itself.\n */\nfunction describeResult(result: ScreenResult): string {\n  const lines = [\n    `verdict: ${result.verdict}`,\n    `trust score: ${result.trustScore}`,\n    `confidence: ${result.confidence}`,\n    `source: ${result.source}`,\n  ];\n  if (result.reasons.length > 0) {\n    lines.push(`reasons: ${result.reasons.join(\"; \")}`);\n  }\n  if (result.policyHits.length > 0) {\n    lines.push(`policy hits: ${result.policyHits.join(\"; \")}`);\n  }\n  return lines.join(\"\\n\");\n}\n\n/**\n * Build the Frisk MCP server.\n *\n * One tool, deliberately. `screen_payment` is the whole deterministic floor:\n * counterparty sanity, dynamic-payTo comparison, transport check, and the\n * caller's own spending policy. With an API key the same call is answered by\n * the hosted service, which adds reputation signals.\n *\n * Note on where this belongs: an MCP tool runs when a model decides to call it,\n * so it is a weaker guarantee than calling `screen()` on the code path that\n * actually signs the payment. Use this for inspection and for agents that\n * cannot import the library; use the library where the money moves.\n */\nexport function createServer(options: ServerOptions = {}): McpServer {\n  const client = new Client({\n    apiKey: options.apiKey,\n    baseUrl: options.baseUrl,\n  });\n\n  const server = new McpServer({\n    name: \"frisk\",\n    version: \"0.0.1\",\n  });\n\n  server.registerTool(\n    \"screen_payment\",\n    {\n      title: \"Screen a payment before paying\",\n      description:\n        client.mode === \"hosted\"\n          ? \"Screen a counterparty an agent is about to pay. Runs the local deterministic checks and the hosted reputation graph, and returns allow / review / block with reasons. Advisory: the caller decides.\"\n          : \"Screen a counterparty an agent is about to pay. Runs entirely offline: address sanity, dynamic-payTo comparison, transport check, and your spending policy. Returns allow / review / block with reasons. Advisory: the caller decides. Set FRISK_API_KEY to add hosted reputation signals.\",\n      inputSchema,\n      annotations: {\n        readOnlyHint: true,\n        openWorldHint: client.mode === \"hosted\",\n      },\n    },\n    async ({ counterparty, maxPerCall, allowedAssets, ...rest }) => {\n      const policy =\n        maxPerCall === undefined && allowedAssets === undefined\n          ? undefined\n          : { maxPerCall, allowedAssets };\n      try {\n        const result = await client.screen(counterparty, { ...rest, policy });\n        return {\n          content: [{ type: \"text\" as const, text: describeResult(result) }],\n          structuredContent: { ...result },\n        };\n      } catch (error) {\n        const message = error instanceof Error ? error.message : String(error);\n        return {\n          isError: true,\n          content: [\n            {\n              type: \"text\" as const,\n              text: `screening failed: ${message}`,\n            },\n          ],\n        };\n      }\n    },\n  );\n\n  return server;\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "frisk-mcp",
+  "version": "0.0.1",
+  "description": "MCP server for Frisk: screen an x402 payment counterparty before an agent pays.",
+  "mcpName": "dev.tryfrisk/frisk",
+  "type": "module",
+  "bin": {
+    "frisk-mcp": "./dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check .",
+    "format": "biome check --write .",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "ai-agents",
+    "x402",
+    "agent-payments",
+    "risk"
+  ],
+  "license": "MIT",
+  "author": "Frisk contributors",
+  "homepage": "https://github.com/Jiangw2718i/frisk#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Jiangw2718i/frisk.git",
+    "directory": "mcp"
+  },
+  "bugs": {
+    "url": "https://github.com/Jiangw2718i/frisk/issues"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/server": "^2.0.0",
+    "frisk-screen": "^0.0.2",
+    "zod": "^4.2.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.16",
+    "@modelcontextprotocol/client": "^2.0.0",
+    "@types/node": "^25.9.3",
+    "tsup": "^8.5.1",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.8"
+  }
+}