@agentutility/mcp-matchpoint 0.1.0

package/README.md

@@ -0,0 +1,80 @@
+# @agentutility/mcp-matchpoint
+
+> Dedup and record linkage, per call.
+
+Turn messy company names, people, addresses, emails, and phones into stable match keys so duplicates collide — plus a similarity score to rank candidate pairs. The dedup/entity-resolution primitives a data-enrichment agent needs.
+
+**Pricing:** pay-per-call in USDC on Base. No subscriptions, no API keys. See per-tool prices below.
+
+## Install — Claude Desktop
+
+Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+
+```json
+{
+  "mcpServers": {
+    "agentutility-matchpoint": {
+      "command": "npx",
+      "args": ["-y", "@agentutility/mcp-matchpoint"],
+      "env": { "X402_PRIVATE_KEY": "0xYOUR_PRIVATE_KEY_HEX" }
+    }
+  }
+}
+```
+
+Restart Claude Desktop. 7 tools appear in the tool palette.
+
+## Install — Cursor
+
+Add to `.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "agentutility-matchpoint": {
+      "command": "npx",
+      "args": ["-y", "@agentutility/mcp-matchpoint"],
+      "env": { "X402_PRIVATE_KEY": "0x..." }
+    }
+  }
+}
+```
+
+## Funding
+
+Send any amount of **USDC on Base mainnet** to the address derived from your `X402_PRIVATE_KEY`. The MCP server uses it to pay for tool calls automatically.
+
+USDC on Base contract: `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`
+
+## Tools (7)
+
+| Tool | Description |
+|---|---|
+| `address-parse` | (0.002 USDC/call) Address parser / parse street address into components / address splitter / USPS field extraction. Splits a freeform US address into number, street, unit, city, state, and zip. Deterministic, best-effort, no geocoding, no upstream. |
+| `match-key-address` | (0.002 USDC/call) Address match key / postal address dedup / USPS-style standardization / address record linkage. Expands street types (St to Street), directionals (N to North), and unit designators (Apt/Ste/# to unit), then builds a stable key so '123 Main St Apt 4' and '123 Main Street #4' collide. Pure compute, no geocoding, no upstream. |
+| `match-key-company` | (0.002 USDC/call) Company name match key / business-name dedup / entity resolution / fuzzy company matching / record linkage. Deterministic similarity key: strips legal suffixes (Inc, LLC, Corp, Ltd, GmbH), punctuation, and abbreviations, then phonetic-encodes tokens so 'IBM Corp' and 'I.B.M. Corporation, Inc.' produce the same key. Pure compute, no upstream. Use it to dedup CRM/lead lists and join company records across sources. |
+| `match-key-email` | (0.002 USDC/call) Email match key / email dedup / email normalization / contact record linkage. Collapses Gmail dots and '+tag' subaddressing and lowercases the domain so 'John.Doe+promo@Gmail.com' and 'johndoe@gmail.com' share a key. Reports basic syntax validity and the domain. Pure compute, no SMTP/MX lookup, no upstream. |
+| `match-key-name` | (0.002 USDC/call) Person name match key / contact dedup / people record linkage / fuzzy name matching. Canonicalizes nicknames (Bob to Robert), folds accents, drops titles/suffixes (Mr, Jr, PhD), and is order-insensitive so 'Smith, Robert' and 'Bob Smith' share a key. Returns first/last too. Pure compute, no upstream. |
+| `match-key-phone` | (0.002 USDC/call) Phone match key / phone number dedup / phone normalization / E.164 formatter / contact record linkage. Strips formatting to digits and produces a canonical E.164 key so '(415) 555-0100' and '+1 415-555-0100' collide. Returns E.164, country code, and validity. Pure compute, no carrier lookup, no upstream. |
+| `match-score` | (0.003 USDC/call) Fuzzy match score / string similarity / record-pair scoring / dedup confidence. Compares two values of a given type (company, name, address, email, phone, or text) and returns a 0-100 similarity score blending match-key equality, Jaro-Winkler, and token overlap, plus whether they share a match key. The companion to the match-key endpoints: bucket by key, then rank candidates by score. Pure compute, no upstream. |
+
+## How it works
+
+1. Agent calls a tool (e.g. `address-parse`).
+2. MCP server POSTs to `https://x402.agentutility.ai/address-parse`.
+3. The endpoint responds **HTTP 402** with payment instructions.
+4. The MCP server signs an EIP-3009 USDC transfer authorization with `X402_PRIVATE_KEY` and retries.
+5. CDP facilitator settles on Base.
+6. The endpoint returns the actual response.
+
+The agent never sees the payment flow — it just gets the result.
+
+## Links
+
+- Cluster overview: https://agentutility.ai/matchpoint/
+- All MCP packages: https://mcp.agentutility.ai/
+- Source: https://github.com/rooz21/x402/tree/main/packages/mcp-matchpoint
+
+---
+
+**Version:** 0.1.0 · **License:** MIT

package/dist/index.js

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+/**
+ * @agentutility/mcp-<cluster> — stdio MCP server exposing the cluster's
+ * x402-paid endpoints as MCP tools. Forwards every CallToolRequest to
+ * x402.agentutility.ai, where @x402/fetch handles 402 → payment → retry
+ * using the agent's own wallet (X402_PRIVATE_KEY env var).
+ *
+ * Boilerplate is single-sourced at packages/_template/src/index.ts and
+ * copied verbatim into each packages/mcp-<cluster>/src/index.ts by
+ * scripts/generate-mcp-clusters.mjs. The codegen also writes a matching
+ * tools.generated.ts so this file imports CLUSTER_SLUG + VERSION + TOOLS
+ * rather than hard-coding.
+ *
+ * Required env: X402_PRIVATE_KEY (hex EVM key, USDC on Base).
+ * Optional env: X402_BASE_URL (default https://x402.agentutility.ai)
+ *               X402_RPC_URL  (default https://mainnet.base.org)
+ */
+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 { wrapFetchWithPayment, x402Client } from "@x402/fetch";
+import { ExactEvmScheme, toClientEvmSigner } from "@x402/evm";
+import { privateKeyToAccount } from "viem/accounts";
+import { createPublicClient, http } from "viem";
+import { base } from "viem/chains";
+import { TOOLS, CLUSTER_SLUG, VERSION } from "./tools.generated.js";
+const BASE_URL = (process.env.X402_BASE_URL || "https://x402.agentutility.ai").replace(/\/$/, "");
+const RPC_URL = process.env.X402_RPC_URL || "https://mainnet.base.org";
+const PK = process.env.X402_PRIVATE_KEY;
+if (!PK) {
+    console.error(`[@agentutility/mcp-${CLUSTER_SLUG}] FATAL: X402_PRIVATE_KEY env var is required.`);
+    console.error("Set it to a hex-encoded EVM private key with USDC balance on Base (chain 8453).");
+    console.error("USDC on Base: 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913");
+    process.exit(1);
+}
+const account = privateKeyToAccount((PK.startsWith("0x") ? PK : `0x${PK}`));
+const publicClient = createPublicClient({
+    chain: base,
+    transport: http(RPC_URL),
+});
+const signer = toClientEvmSigner(account, publicClient);
+const client = new x402Client().register("eip155:8453", new ExactEvmScheme(signer));
+const paidFetch = wrapFetchWithPayment(fetch, client);
+async function trackedFetch(url, init) {
+    const headers = new Headers(init?.headers);
+    headers.set("X-Agent-Channel", `mcp-stdio-${CLUSTER_SLUG}`);
+    headers.set("X-Agent-Id", "47167");
+    if (!headers.has("User-Agent")) {
+        headers.set("User-Agent", `agentutility-mcp/${CLUSTER_SLUG}/${VERSION}`);
+    }
+    return paidFetch(url, { ...init, headers });
+}
+const server = new Server({ name: `agentutility-${CLUSTER_SLUG}`, version: VERSION }, { capabilities: { tools: {} } });
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: TOOLS.map((t) => ({
+        name: t.name,
+        description: t.description,
+        inputSchema: t.input_schema,
+    })),
+}));
+server.setRequestHandler(CallToolRequestSchema, async (req) => {
+    const name = req.params.name;
+    const tool = TOOLS.find((t) => t.name === name);
+    if (!tool) {
+        return { content: [{ type: "text", text: `Unknown tool: ${name}` }], isError: true };
+    }
+    try {
+        const res = await trackedFetch(`${BASE_URL}/${tool.http_name}`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(req.params.arguments ?? {}),
+        });
+        const body = await res.text();
+        if (!res.ok) {
+            return { content: [{ type: "text", text: `HTTP ${res.status}: ${body}` }], isError: true };
+        }
+        return { content: [{ type: "text", text: body }] };
+    }
+    catch (err) {
+        return {
+            content: [{ type: "text", text: `tool call failed: ${err instanceof Error ? err.message : String(err)}` }],
+            isError: true,
+        };
+    }
+});
+await server.connect(new StdioServerTransport());

package/dist/tools.generated.js

@@ -0,0 +1,152 @@
+/** Auto-generated by scripts/generate-mcp-clusters.mjs. Do not edit by hand. */
+export const CLUSTER_SLUG = "matchpoint";
+export const VERSION = "0.1.0";
+export const TOOLS = [
+    {
+        "name": "address-parse",
+        "http_name": "address-parse",
+        "description": "(0.002 USDC/call) Address parser / parse street address into components / address splitter / USPS field extraction. Splits a freeform US address into number, street, unit, city, state, and zip. Deterministic, best-effort, no geocoding, no upstream.",
+        "method": "POST",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "address": {
+                    "type": "string",
+                    "description": "Freeform US street address."
+                }
+            },
+            "required": [
+                "address"
+            ]
+        }
+    },
+    {
+        "name": "match-key-address",
+        "http_name": "match-key-address",
+        "description": "(0.002 USDC/call) Address match key / postal address dedup / USPS-style standardization / address record linkage. Expands street types (St to Street), directionals (N to North), and unit designators (Apt/Ste/# to unit), then builds a stable key so '123 Main St Apt 4' and '123 Main Street #4' collide. Pure compute, no geocoding, no upstream.",
+        "method": "POST",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "address": {
+                    "type": "string",
+                    "description": "Freeform US street address."
+                }
+            },
+            "required": [
+                "address"
+            ]
+        }
+    },
+    {
+        "name": "match-key-company",
+        "http_name": "match-key-company",
+        "description": "(0.002 USDC/call) Company name match key / business-name dedup / entity resolution / fuzzy company matching / record linkage. Deterministic similarity key: strips legal suffixes (Inc, LLC, Corp, Ltd, GmbH), punctuation, and abbreviations, then phonetic-encodes tokens so 'IBM Corp' and 'I.B.M. Corporation, Inc.' produce the same key. Pure compute, no upstream. Use it to dedup CRM/lead lists and join company records across sources.",
+        "method": "POST",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "name": {
+                    "type": "string",
+                    "description": "Company / organization name."
+                }
+            },
+            "required": [
+                "name"
+            ]
+        }
+    },
+    {
+        "name": "match-key-email",
+        "http_name": "match-key-email",
+        "description": "(0.002 USDC/call) Email match key / email dedup / email normalization / contact record linkage. Collapses Gmail dots and '+tag' subaddressing and lowercases the domain so 'John.Doe+promo@Gmail.com' and 'johndoe@gmail.com' share a key. Reports basic syntax validity and the domain. Pure compute, no SMTP/MX lookup, no upstream.",
+        "method": "POST",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "email": {
+                    "type": "string",
+                    "description": "Email address."
+                }
+            },
+            "required": [
+                "email"
+            ]
+        }
+    },
+    {
+        "name": "match-key-name",
+        "http_name": "match-key-name",
+        "description": "(0.002 USDC/call) Person name match key / contact dedup / people record linkage / fuzzy name matching. Canonicalizes nicknames (Bob to Robert), folds accents, drops titles/suffixes (Mr, Jr, PhD), and is order-insensitive so 'Smith, Robert' and 'Bob Smith' share a key. Returns first/last too. Pure compute, no upstream.",
+        "method": "POST",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "name": {
+                    "type": "string",
+                    "description": "Person full name. 'Last, First' accepted."
+                }
+            },
+            "required": [
+                "name"
+            ]
+        }
+    },
+    {
+        "name": "match-key-phone",
+        "http_name": "match-key-phone",
+        "description": "(0.002 USDC/call) Phone match key / phone number dedup / phone normalization / E.164 formatter / contact record linkage. Strips formatting to digits and produces a canonical E.164 key so '(415) 555-0100' and '+1 415-555-0100' collide. Returns E.164, country code, and validity. Pure compute, no carrier lookup, no upstream.",
+        "method": "POST",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "phone": {
+                    "type": "string",
+                    "description": "Phone number in any format."
+                },
+                "region": {
+                    "type": "string",
+                    "description": "Default region for numbers without a country code. Default 'US'."
+                }
+            },
+            "required": [
+                "phone"
+            ]
+        }
+    },
+    {
+        "name": "match-score",
+        "http_name": "match-score",
+        "description": "(0.003 USDC/call) Fuzzy match score / string similarity / record-pair scoring / dedup confidence. Compares two values of a given type (company, name, address, email, phone, or text) and returns a 0-100 similarity score blending match-key equality, Jaro-Winkler, and token overlap, plus whether they share a match key. The companion to the match-key endpoints: bucket by key, then rank candidates by score. Pure compute, no upstream.",
+        "method": "POST",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "a": {
+                    "type": "string",
+                    "description": "First value."
+                },
+                "b": {
+                    "type": "string",
+                    "description": "Second value."
+                },
+                "type": {
+                    "type": "string",
+                    "enum": [
+                        "company",
+                        "name",
+                        "address",
+                        "email",
+                        "phone",
+                        "text"
+                    ],
+                    "description": "Value type. Default 'text'."
+                }
+            },
+            "required": [
+                "a",
+                "b"
+            ]
+        }
+    }
+];

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@agentutility/mcp-matchpoint",
+  "version": "0.1.0",
+  "description": "MCP server for the @agentutility matchpoint cluster — pay-per-call x402 tools, no API keys, USDC on Base.",
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "agentutility-mcp-matchpoint": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/rooz21/x402",
+    "directory": "packages/mcp-matchpoint"
+  },
+  "homepage": "https://mcp.agentutility.ai/matchpoint/",
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "x402",
+    "agentutility",
+    "agent-tools",
+    "matchpoint"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.4",
+    "@x402/fetch": "^2.12.0",
+    "@x402/evm": "^2.12.0",
+    "viem": "^2.21.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.5.0"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}