base-escrow-mcp 1.0.0

package/README.md

@@ -0,0 +1,60 @@
+# base-escrow-mcp
+
+MCP server for AI agents to create and manage P2P escrow deals on Base (ETH or ERC-20).
+
+## Install
+
+```bash
+npx -y base-escrow-mcp
+```
+
+Or add to your MCP config:
+
+```json
+{
+  "mcpServers": {
+    "base-escrow": {
+      "command": "npx",
+      "args": ["-y", "base-escrow-mcp"],
+      "env": {
+        "DEPLOYER_PRIVATE_KEY": "your-private-key",
+        "RPC_URL": "https://mainnet.base.org"
+      }
+    }
+  }
+}
+```
+
+## Tools (8)
+
+| Tool | Description | Auth |
+|------|-------------|------|
+| `create_escrow` | Create a new escrow deal (ETH or ERC-20) | Key |
+| `release_escrow` | Release funds to seller (buyer only) | Key |
+| `refund_escrow` | Refund funds to buyer | Key |
+| `dispute_escrow` | Flag a dispute on a deal | Key |
+| `get_deal` | Get deal details by ID | None |
+| `get_buyer_deals` | Get all deals for a buyer address | None |
+| `get_seller_deals` | Get all deals for a seller address | None |
+| `get_escrow_info` | Get contract info (fee, total deals, treasury) | None |
+
+## How It Works
+
+1. **Buyer creates** an escrow deal, depositing ETH or tokens into the contract
+2. **Seller delivers** the goods/services off-chain
+3. **Buyer releases** funds to seller, or **refunds** if seller fails to deliver
+4. Either party can **dispute** — treasury resolves disputed deals
+
+## Environment Variables
+
+- `DEPLOYER_PRIVATE_KEY` — Required for write operations (create, release, refund, dispute)
+- `RPC_URL` — Base RPC endpoint (default: `https://mainnet.base.org`)
+
+## Chain
+
+- **Network:** Base mainnet (chainId 8453)
+- **Explorer:** https://basescan.org
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+/**
+ * base-escrow-mcp — MCP server for AI agents to manage P2P escrow deals on Base
+ *
+ * Tools:
+ *   create_escrow    — Create a new escrow deal (ETH or ERC-20)
+ *   release_escrow   — Release funds to seller (buyer only)
+ *   refund_escrow    — Refund funds to buyer
+ *   dispute_escrow   — Flag a dispute
+ *   get_deal         — Get deal details by ID
+ *   get_buyer_deals  — Get all deals for a buyer address
+ *   get_seller_deals — Get all deals for a seller address
+ *   get_escrow_info  — Get contract info (fee, total deals, treasury)
+ */
+export {};

package/dist/index.js

@@ -0,0 +1,324 @@
+#!/usr/bin/env node
+/**
+ * base-escrow-mcp — MCP server for AI agents to manage P2P escrow deals on Base
+ *
+ * Tools:
+ *   create_escrow    — Create a new escrow deal (ETH or ERC-20)
+ *   release_escrow   — Release funds to seller (buyer only)
+ *   refund_escrow    — Refund funds to buyer
+ *   dispute_escrow   — Flag a dispute
+ *   get_deal         — Get deal details by ID
+ *   get_buyer_deals  — Get all deals for a buyer address
+ *   get_seller_deals — Get all deals for a seller address
+ *   get_escrow_info  — Get contract info (fee, total deals, treasury)
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { ethers } from "ethers";
+// ── Config ──────────────────────────────────────────────────────────
+const RPC_URL = process.env.RPC_URL || "https://mainnet.base.org";
+const CHAIN_ID = 8453;
+const ESCROW_ADDRESS = "0x5Ee9f1e1dB3366D79B5fB59Dc012aD7D71a20F2C";
+const ESCROW_ABI = [
+    "function create(address seller, address token, uint256 amount, string description) payable returns (uint256)",
+    "function release(uint256 dealId)",
+    "function refund(uint256 dealId)",
+    "function dispute(uint256 dealId)",
+    "function resolve(uint256 dealId, address winner)",
+    "function getDeal(uint256 dealId) view returns (address buyer, address seller, address token, uint256 amount, uint8 status, uint256 createdAt, string description)",
+    "function getBuyerDeals(address buyer) view returns (uint256[])",
+    "function getSellerDeals(address seller) view returns (uint256[])",
+    "function escrowFee() view returns (uint256)",
+    "function nextDealId() view returns (uint256)",
+    "function treasury() view returns (address)",
+    "function setFee(uint256 newFee)",
+];
+const ERC20_ABI = [
+    "function approve(address spender, uint256 amount) returns (bool)",
+    "function allowance(address owner, address spender) view returns (uint256)",
+    "function balanceOf(address) view returns (uint256)",
+    "function decimals() view returns (uint8)",
+    "function symbol() view returns (string)",
+    "function name() view returns (string)",
+];
+const STATUS_LABELS = ["Active", "Released", "Refunded", "Disputed"];
+// ── Provider & Contract ─────────────────────────────────────────────
+const provider = new ethers.JsonRpcProvider(RPC_URL);
+const escrow = new ethers.Contract(ESCROW_ADDRESS, ESCROW_ABI, provider);
+// ── Helpers ─────────────────────────────────────────────────────────
+function ok(data) {
+    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+}
+function fail(msg) {
+    return { content: [{ type: "text", text: JSON.stringify({ error: msg }, null, 2) }], isError: true };
+}
+function getWallet() {
+    const pk = process.env.DEPLOYER_PRIVATE_KEY;
+    if (!pk)
+        return null;
+    return new ethers.Wallet(pk, provider);
+}
+function formatDeal(dealId, raw) {
+    const [buyer, seller, token, amount, status, createdAt, description] = raw;
+    const isETH = token === ethers.ZeroAddress;
+    return {
+        dealId: Number(dealId),
+        buyer,
+        seller,
+        token: isETH ? "ETH" : token,
+        tokenAddress: token,
+        amount: isETH ? ethers.formatEther(amount) : amount.toString(),
+        amountRaw: amount.toString(),
+        status: STATUS_LABELS[status] ?? "Unknown",
+        statusCode: status,
+        createdAt: Number(createdAt),
+        createdAtISO: new Date(Number(createdAt) * 1000).toISOString(),
+        description,
+    };
+}
+// ── Server ──────────────────────────────────────────────────────────
+const server = new McpServer({
+    name: "base-escrow",
+    version: "1.0.0",
+});
+// --- create_escrow ---
+server.tool("create_escrow", "Create a new P2P escrow deal on Base. For ETH deals, the ETH is locked in the contract. For ERC-20 deals, tokens are transferred from your wallet (approval handled automatically). A flat escrow fee is charged in ETH. Requires DEPLOYER_PRIVATE_KEY env var.", {
+    seller: z.string().describe("Seller wallet address — receives funds when buyer releases"),
+    amount: z.string().describe("Amount to escrow (ETH in ether e.g. '0.01', or token amount in human-readable units)"),
+    description: z.string().describe("Description of the deal / what is being traded"),
+    token: z.string().optional().describe("ERC-20 token address. Omit or set to '0x0000000000000000000000000000000000000000' for ETH escrow"),
+}, async ({ seller, amount, description, token }) => {
+    try {
+        const wallet = getWallet();
+        if (!wallet)
+            return fail("DEPLOYER_PRIVATE_KEY env var required");
+        const isETH = !token || token === ethers.ZeroAddress;
+        const fee = await escrow.escrowFee();
+        let amountWei;
+        let msgValue;
+        const tokenAddress = isETH ? ethers.ZeroAddress : token;
+        if (isETH) {
+            amountWei = ethers.parseEther(amount);
+            msgValue = amountWei + fee;
+        }
+        else {
+            // Get token decimals for parsing
+            const tokenContract = new ethers.Contract(tokenAddress, ERC20_ABI, provider);
+            const decimals = await tokenContract.decimals();
+            amountWei = ethers.parseUnits(amount, decimals);
+            msgValue = fee;
+            // Handle approval
+            const tokenSigned = tokenContract.connect(wallet);
+            const currentAllowance = await tokenContract.allowance(wallet.address, ESCROW_ADDRESS);
+            if (currentAllowance < amountWei) {
+                const approveTx = await tokenSigned.approve(ESCROW_ADDRESS, ethers.MaxUint256);
+                await approveTx.wait();
+            }
+        }
+        const signed = escrow.connect(wallet);
+        const tx = await signed.create(seller, tokenAddress, amountWei, description, { value: msgValue });
+        const receipt = await tx.wait();
+        // Parse DealCreated event to get the dealId
+        const iface = new ethers.Interface(ESCROW_ABI);
+        let dealId;
+        for (const log of receipt.logs) {
+            try {
+                const parsed = iface.parseLog({ topics: log.topics, data: log.data });
+                if (parsed && parsed.name === "DealCreated") {
+                    dealId = parsed.args[0].toString();
+                }
+            }
+            catch {
+                // skip non-matching logs
+            }
+        }
+        return ok({
+            status: "created",
+            dealId: dealId ?? "check tx logs",
+            buyer: wallet.address,
+            seller,
+            token: isETH ? "ETH" : tokenAddress,
+            amount,
+            fee: ethers.formatEther(fee) + " ETH",
+            description,
+            txHash: receipt.hash,
+            explorer: `https://basescan.org/tx/${receipt.hash}`,
+            gasUsed: receipt.gasUsed.toString(),
+        });
+    }
+    catch (err) {
+        return fail(`Create escrow failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+});
+// --- release_escrow ---
+server.tool("release_escrow", "Release escrowed funds to the seller. Only the buyer can call this. Marks the deal as complete. Requires DEPLOYER_PRIVATE_KEY env var.", {
+    deal_id: z.number().describe("Deal ID to release"),
+}, async ({ deal_id }) => {
+    try {
+        const wallet = getWallet();
+        if (!wallet)
+            return fail("DEPLOYER_PRIVATE_KEY env var required");
+        const signed = escrow.connect(wallet);
+        const tx = await signed.release(deal_id);
+        const receipt = await tx.wait();
+        return ok({
+            status: "released",
+            dealId: deal_id,
+            txHash: receipt.hash,
+            explorer: `https://basescan.org/tx/${receipt.hash}`,
+            gasUsed: receipt.gasUsed.toString(),
+        });
+    }
+    catch (err) {
+        return fail(`Release failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+});
+// --- refund_escrow ---
+server.tool("refund_escrow", "Refund escrowed funds back to the buyer. Only the buyer can call this. Use when the seller fails to deliver. Requires DEPLOYER_PRIVATE_KEY env var.", {
+    deal_id: z.number().describe("Deal ID to refund"),
+}, async ({ deal_id }) => {
+    try {
+        const wallet = getWallet();
+        if (!wallet)
+            return fail("DEPLOYER_PRIVATE_KEY env var required");
+        const signed = escrow.connect(wallet);
+        const tx = await signed.refund(deal_id);
+        const receipt = await tx.wait();
+        return ok({
+            status: "refunded",
+            dealId: deal_id,
+            txHash: receipt.hash,
+            explorer: `https://basescan.org/tx/${receipt.hash}`,
+            gasUsed: receipt.gasUsed.toString(),
+        });
+    }
+    catch (err) {
+        return fail(`Refund failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+});
+// --- dispute_escrow ---
+server.tool("dispute_escrow", "Flag a dispute on an active escrow deal. Either buyer or seller can call this. Funds stay locked until the treasury resolves the dispute. Requires DEPLOYER_PRIVATE_KEY env var.", {
+    deal_id: z.number().describe("Deal ID to dispute"),
+}, async ({ deal_id }) => {
+    try {
+        const wallet = getWallet();
+        if (!wallet)
+            return fail("DEPLOYER_PRIVATE_KEY env var required");
+        const signed = escrow.connect(wallet);
+        const tx = await signed.dispute(deal_id);
+        const receipt = await tx.wait();
+        return ok({
+            status: "disputed",
+            dealId: deal_id,
+            txHash: receipt.hash,
+            explorer: `https://basescan.org/tx/${receipt.hash}`,
+            gasUsed: receipt.gasUsed.toString(),
+            note: "Funds are locked. Treasury will resolve the dispute.",
+        });
+    }
+    catch (err) {
+        return fail(`Dispute failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+});
+// --- get_deal ---
+server.tool("get_deal", "Get details of an escrow deal by its ID. Returns buyer, seller, token, amount, status, creation time, and description.", {
+    deal_id: z.number().describe("Deal ID to look up"),
+}, async ({ deal_id }) => {
+    try {
+        const raw = await escrow.getDeal(deal_id);
+        const deal = formatDeal(deal_id, raw);
+        return ok({ deal });
+    }
+    catch (err) {
+        return fail(`Get deal failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+});
+// --- get_buyer_deals ---
+server.tool("get_buyer_deals", "Get all escrow deal IDs where the given address is the buyer.", {
+    address: z.string().describe("Buyer wallet address"),
+}, async ({ address }) => {
+    try {
+        const dealIds = await escrow.getBuyerDeals(address);
+        const ids = dealIds.map((id) => Number(id));
+        // Fetch details for each deal
+        const deals = await Promise.all(ids.map(async (id) => {
+            const raw = await escrow.getDeal(id);
+            return formatDeal(id, raw);
+        }));
+        return ok({
+            address,
+            role: "buyer",
+            totalDeals: ids.length,
+            dealIds: ids,
+            deals,
+        });
+    }
+    catch (err) {
+        return fail(`Get buyer deals failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+});
+// --- get_seller_deals ---
+server.tool("get_seller_deals", "Get all escrow deal IDs where the given address is the seller.", {
+    address: z.string().describe("Seller wallet address"),
+}, async ({ address }) => {
+    try {
+        const dealIds = await escrow.getSellerDeals(address);
+        const ids = dealIds.map((id) => Number(id));
+        const deals = await Promise.all(ids.map(async (id) => {
+            const raw = await escrow.getDeal(id);
+            return formatDeal(id, raw);
+        }));
+        return ok({
+            address,
+            role: "seller",
+            totalDeals: ids.length,
+            dealIds: ids,
+            deals,
+        });
+    }
+    catch (err) {
+        return fail(`Get seller deals failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+});
+// --- get_escrow_info ---
+server.tool("get_escrow_info", "Get Escrow contract info — current fee, total deals created, treasury address, contract address. Use to verify the contract is live.", {}, async () => {
+    try {
+        const [fee, totalDeals, treasury] = await Promise.all([
+            escrow.escrowFee(),
+            escrow.nextDealId(),
+            escrow.treasury(),
+        ]);
+        return ok({
+            contract: ESCROW_ADDRESS,
+            chain: "Base",
+            chainId: CHAIN_ID,
+            escrowFee: ethers.formatEther(fee) + " ETH",
+            escrowFeeWei: fee.toString(),
+            totalDeals: Number(totalDeals),
+            treasury,
+            explorer: `https://basescan.org/address/${ESCROW_ADDRESS}`,
+            capabilities: [
+                "P2P escrow for ETH or any ERC-20 token",
+                "Buyer creates deal, deposits funds",
+                "Buyer releases funds to seller on delivery",
+                "Buyer can refund if seller fails to deliver",
+                "Either party can flag a dispute",
+                "Treasury resolves disputes",
+                "Flat fee per escrow creation",
+            ],
+        });
+    }
+    catch (err) {
+        return fail(`Info fetch failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+});
+// ── Start ───────────────────────────────────────────────────────────
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((err) => {
+    console.error("base-escrow-mcp error:", err);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "base-escrow-mcp",
+  "version": "1.0.0",
+  "description": "MCP server for AI agents to create and manage P2P escrow deals (ETH or ERC-20) on Base. Trustless trades with dispute resolution — one tool call.",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "base-escrow-mcp": "dist/index.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "dist/",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsc --watch"
+  },
+  "keywords": [
+    "mcp",
+    "base",
+    "escrow",
+    "p2p",
+    "erc20",
+    "eth",
+    "dispute",
+    "trade",
+    "ai-agent",
+    "claude",
+    "cursor",
+    "model-context-protocol",
+    "onchain"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "ethers": "^6.13.0",
+    "zod": "^3.22.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.4.0"
+  }
+}