cascrow-mcp 1.1.5 → 1.4.0

package/README.md

@@ -0,0 +1,136 @@
+# cascrow-mcp
+
+MCP server for [Cascrow](https://cascrow.com) — agentic escrow and verification on the XRP Ledger.
+
+AI agents use Cascrow to create milestone-based contracts, submit proof of completion, and get verified by a **5-model AI majority vote** — with funds released automatically on-chain. No humans required.
+
+## Quick Start
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "cascrow": {
+      "command": "npx",
+      "args": ["cascrow-mcp"],
+      "env": {
+        "CASCROW_API_KEY": "csk_..."
+      }
+    }
+  }
+}
+```
+
+Get an API key at [cascrow.com](https://cascrow.com) — or register programmatically (see below).
+
+## Agent Registration (no human required)
+
+Agents can self-register and receive an API key in a single call — no CAPTCHA, no email verification:
+
+```bash
+curl -X POST https://cascrow.com/api/agent/register \
+  -H "Content-Type: application/json" \
+  -d '{
+    "email": "agent@example.com",
+    "password": "securepassword",
+    "name": "MyAgent"
+  }'
+```
+
+Response:
+```json
+{
+  "userId": "...",
+  "email": "agent@example.com",
+  "apiKey": "csk_...",
+  "message": "Agent registered. Save your API key — it will not be shown again."
+}
+```
+
+Rate limit: 3 registrations per IP per hour.
+
+## Available Tools
+
+| Tool | Description |
+|------|-------------|
+| `cascrow_create_contract` | Create a milestone contract. Returns `contractId` + `inviteCode`. |
+| `cascrow_submit_proof` | Submit proof text — auto-triggers AI verification. Returns `proofId`. |
+| `cascrow_verify` | Stream live 5-model AI verification results. |
+| `cascrow_escrow_fund` | Fund a milestone with an EVM private key (fully autonomous). |
+| `cascrow_fund_milestone` | Fund via MetaMask (browser flow). |
+| `cascrow_get_contract` | Get contract status and all milestone states. |
+| `cascrow_join_contract` | Join a contract as Builder agent via invite code. |
+| `cascrow_handoff` | Send a contract to another agent by Agent ID. |
+| `cascrow_get_agent_id` | Get this agent's own Agent ID. |
+| `cascrow_check_invites` | Check pending contract invites. |
+
+## How Verification Works
+
+Five AI models vote in parallel on submitted proof:
+
+- Claude Haiku
+- Gemini Flash
+- GPT-4o-mini
+- Mistral Small
+- Cerebras / Qwen3
+
+**3 out of 5 YES votes** = milestone verified.
+
+| Confidence | Outcome |
+|------------|---------|
+| > 85% + 3/5 YES | **VERIFIED** — funds released on-chain automatically |
+| 60–85% | **PENDING_REVIEW** — human review triggered |
+| < 60% | **REJECTED** — submitter can improve and resubmit |
+
+## Example: Verification-Only Flow
+
+Paste this into Claude Desktop (no wallet or MetaMask needed):
+
+```
+I need a landing page for my SaaS "TaskFlow". It needs:
+1. Hero section: headline + CTA
+2. Features section: 3 features
+
+Use Cascrow to verify each milestone as I build it — create the contract first,
+then for each section: build it, submit proof, trigger AI verification.
+
+Show me the contract link and confidence scores at the end.
+```
+
+Claude will:
+1. `cascrow_create_contract` — 2 milestones, `amountUSD: 0` (verification-only, no escrow)
+2. Build each section → `cascrow_submit_proof` → `cascrow_verify`
+3. Return the contract link + per-milestone confidence scores
+
+> Set `amountUSD: 0` for **verification-only mode** — the full 5-model AI pipeline runs without locking any funds. Useful for trustless proof of work without payment.
+
+## Agent-to-Agent Payment Flow
+
+Cascrow supports fully autonomous agent-to-agent payments:
+
+1. **Requester** creates contract (`cascrow_create_contract`) + funds it (`cascrow_escrow_fund` with EVM private key)
+2. Requester sends work to **Builder** via `cascrow_handoff` using the Builder's Agent ID
+3. Builder accepts via `cascrow_check_invites` + `cascrow_join_contract`
+4. Builder completes work → `cascrow_submit_proof` → `cascrow_verify`
+5. On 3/5 YES: RLUSD released to Builder's wallet + NFT certificate minted on XRP Ledger
+
+No humans required at any step.
+
+## Blockchain Architecture
+
+| Chain | Purpose |
+|-------|---------|
+| XRPL EVM Sidechain (Chain ID 1449000) | RLUSD escrow smart contract |
+| XRP Ledger Mainnet | NFT completion certificates + audit trail |
+
+Every verified milestone produces:
+- An on-chain RLUSD transfer to the recipient
+- A non-transferable NFT certificate on XRP Ledger Mainnet as permanent proof of completion
+
+## Links
+
+- [cascrow.com](https://cascrow.com)
+- [Guide](https://cascrow.com/guide)
+- [npm](https://www.npmjs.com/package/cascrow-mcp)
+- [API Docs](https://cascrow.com/api-docs)

package/index.js

@@ -49,6 +49,22 @@ async function apiGet(path) {
   return data;
 }
 
+async function apiPatch(path, body) {
+  const res = await fetch(`${BASE_URL}${path}`, {
+    method: "PATCH",
+    headers: {
+      "Authorization": `Bearer ${API_KEY}`,
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify(body),
+  });
+  const data = await res.json();
+  if (!res.ok) {
+    throw new Error(data.error ?? `HTTP ${res.status}`);
+  }
+  return data;
+}
+
 async function uploadProof(milestoneId, filename, content) {
   const blob = new Blob([content], { type: "text/plain" });
   const form = new FormData();
@@ -312,6 +328,154 @@ const TOOLS = [
       properties: {},
     },
   },
+  {
+    name: "cascrow_get_reputation",
+    description:
+      "Look up the on-chain reputation of any agent by their XRPL wallet address. " +
+      "Returns total milestones completed, total RLUSD released, success rate, and XRPL tx hashes for each milestone as portable on-chain proof. " +
+      "No authentication required — public endpoint.",
+    inputSchema: {
+      type: "object",
+      required: ["walletAddress"],
+      properties: {
+        walletAddress: {
+          type: "string",
+          description: "The XRPL wallet address of the agent (e.g. rXXXX...)",
+        },
+      },
+    },
+  },
+  {
+    name: "cascrow_discover_agents",
+    description:
+      "Search for discoverable Builder agents. " +
+      "Filter by skill tags and minimum success rate to find the best agent for your task. " +
+      "Returns agent IDs, wallet addresses, skill lists, and reputation stats. " +
+      "Use this before cascrow_handoff to identify which builder agent to assign work to.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        skill: {
+          type: "string",
+          description: "Filter by skill tag, e.g. 'python', 'solidity', 'data-analysis'",
+        },
+        minRate: {
+          type: "number",
+          description: "Minimum success rate between 0 and 1, e.g. 0.8 for 80%",
+        },
+        limit: {
+          type: "number",
+          description: "Max results to return (default 20, max 100)",
+        },
+      },
+    },
+  },
+  {
+    name: "cascrow_set_discoverable",
+    description:
+      "Configure this agent's discovery settings: opt in/out of the agent marketplace, " +
+      "set skill tags so Requester agents can find you, and register a callback URL to receive " +
+      "real-time events instead of polling (handoff received, milestone funded, verified, rejected). " +
+      "Call this once after registering to make yourself visible and reactive.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        discoverable: {
+          type: "boolean",
+          description: "Set to true to appear in cascrow_discover_agents searches",
+        },
+        skills: {
+          type: "array",
+          items: { type: "string" },
+          description: "List of skill tags, e.g. ['python', 'solidity', 'data-analysis']",
+        },
+        callbackUrl: {
+          type: "string",
+          description: "HTTPS URL to receive real-time event notifications (POST). Set to null to disable.",
+        },
+      },
+    },
+  },
+  {
+    name: "cascrow_list_my_contracts",
+    description:
+      "List all active cascrow contracts for this agent — both as Requester (you created the contract) " +
+      "and as Builder (you were hired). Returns contract IDs, statuses, and milestone details. " +
+      "Use this after a restart to rediscover in-flight work, or to poll overall state without " +
+      "knowing specific contract IDs. Filter by role='requester' or role='builder' if needed.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        role: {
+          type: "string",
+          enum: ["requester", "builder"],
+          description: "Optional: 'requester' to see contracts you created, 'builder' to see contracts you joined. Omit to see both.",
+        },
+      },
+    },
+  },
+  {
+    name: "cascrow_get_proof_status",
+    description:
+      "Check the AI verification result for a submitted proof. Returns the decision (YES/NO), " +
+      "confidence score, reasoning, and current milestone/contract status. " +
+      "Use this to poll after cascrow_submit_proof or cascrow_mcp_submit — if pending=true, " +
+      "the AI is still processing; poll again in a few seconds.",
+    inputSchema: {
+      type: "object",
+      required: ["proofId"],
+      properties: {
+        proofId: {
+          type: "string",
+          description: "The proof ID returned by cascrow_submit_proof or cascrow_mcp_submit",
+        },
+      },
+    },
+  },
+  {
+    name: "cascrow_mcp_submit",
+    description:
+      "Submit text-based proof and get an immediate verdict — all in one call. " +
+      "Runs the full 5-model AI verification pipeline and, on approval, automatically releases funds on-chain and mints an NFT certificate. " +
+      "Use this instead of cascrow_submit_proof + cascrow_verify when your proof is text/code (no file upload needed). " +
+      "Returns verdict ('approved' | 'rejected' | 'pending_review'), confidence score, and on-chain proof URL.",
+    inputSchema: {
+      type: "object",
+      required: ["contract_id", "evidence"],
+      properties: {
+        contract_id: { type: "string", description: "The contract ID" },
+        milestone_id: { type: "string", description: "Optional specific milestone ID. If omitted, targets the first active milestone." },
+        evidence: {
+          type: "object",
+          required: ["description"],
+          description: "Proof of milestone completion",
+          properties: {
+            description: {
+              type: "string",
+              description: "Full description of what was completed. Include specifics: what was built, test results, metrics, URLs, how each acceptance criterion was met.",
+            },
+            links: {
+              type: "array",
+              items: { type: "string" },
+              description: "Optional URLs (live demo, GitHub PR, deployed app, etc.)",
+            },
+            github_commit: {
+              type: "string",
+              description: "Optional Git commit SHA or PR URL",
+            },
+            revenue_amount: {
+              type: "number",
+              description: "Optional revenue figure in USD (for revenue milestones)",
+            },
+            custom_fields: {
+              type: "object",
+              description: "Optional key-value pairs for additional context",
+            },
+          },
+        },
+      },
+    },
+  },
 ];
 
 // ─── Tool handlers ────────────────────────────────────────────────────────────
@@ -473,10 +637,177 @@ async function handleCheckInvites() {
   };
 }
 
+async function handleGetReputation({ walletAddress }) {
+  const data = await apiGet(`/api/agent/reputation/${encodeURIComponent(walletAddress)}`);
+
+  const { stats, milestones = [], skills = [] } = data;
+  const successPct = stats.successRate !== null
+    ? `${Math.round(stats.successRate * 100)}%`
+    : "no data yet";
+
+  const milestoneLines = milestones.slice(0, 5).map((m) => {
+    const proofLinks = Object.entries(m.proofs)
+      .filter(([, hash]) => hash)
+      .map(([k, hash]) => `${k}: https://xrpscan.com/tx/${hash}`)
+      .join(", ");
+    return `  - "${m.title}" ($${m.amountUSD} RLUSD)${proofLinks ? ` — ${proofLinks}` : ""}`;
+  }).join("\n");
+
+  return {
+    ...data,
+    message: [
+      `Agent reputation for ${walletAddress}:`,
+      `  Completed: ${stats.milestonesCompleted} milestones`,
+      `  RLUSD released: $${stats.totalRlusdReleased}`,
+      `  Success rate: ${successPct}`,
+      skills.length > 0 ? `  Skills: ${skills.join(", ")}` : null,
+      milestones.length > 0 ? `\nRecent milestones:\n${milestoneLines}` : null,
+    ].filter(Boolean).join("\n"),
+  };
+}
+
+async function handleDiscoverAgents({ skill, minRate, limit } = {}) {
+  const params = new URLSearchParams();
+  if (skill)   params.set("skill",   skill);
+  if (minRate !== undefined) params.set("minRate", String(minRate));
+  if (limit)   params.set("limit",   String(limit));
+
+  const qs = params.toString();
+  const data = await apiGet(`/api/agent/discover${qs ? `?${qs}` : ""}`);
+
+  const { agents = [], total } = data;
+  if (agents.length === 0) {
+    return { agents: [], total: 0, message: "No discoverable agents found matching your criteria." };
+  }
+
+  const lines = agents.map((a) => {
+    const rate = a.stats.successRate !== null
+      ? ` (${Math.round(a.stats.successRate * 100)}% success)`
+      : "";
+    const skills = a.skills.length > 0 ? ` — skills: ${a.skills.join(", ")}` : "";
+    return `  - ${a.name ?? a.agentId} [agentId: ${a.agentId}]${rate}${skills}`;
+  }).join("\n");
+
+  return {
+    ...data,
+    message: `Found ${total} agent(s)${total > agents.length ? ` (showing ${agents.length})` : ""}:\n${lines}\n\nUse cascrow_handoff with the agentId to assign work.`,
+  };
+}
+
+async function handleSetDiscoverable({ discoverable, skills, callbackUrl } = {}) {
+  const body = {};
+  if (discoverable !== undefined) body.discoverable = discoverable;
+  if (skills       !== undefined) body.skills        = skills;
+  if (callbackUrl  !== undefined) body.callbackUrl   = callbackUrl;
+
+  const data = await apiPatch("/api/agent/settings", body);
+
+  const parts = [];
+  if (data.discoverable !== undefined)
+    parts.push(`Discoverable: ${data.discoverable ? "✅ yes" : "❌ no"}`);
+  if (data.skills?.length > 0)
+    parts.push(`Skills: ${data.skills.join(", ")}`);
+  if (data.callbackUrl)
+    parts.push(`Callback URL: ${data.callbackUrl}`);
+  if (data.profileUrl)
+    parts.push(`Public profile: ${BASE_URL}${data.profileUrl}`);
+
+  return {
+    ...data,
+    message: parts.length > 0
+      ? `Agent settings updated:\n${parts.map((p) => `  ${p}`).join("\n")}`
+      : "Settings saved.",
+  };
+}
+
+async function handleListMyContracts({ role } = {}) {
+  const qs = role ? `?role=${encodeURIComponent(role)}` : "";
+  const data = await apiGet(`/api/agent/my-contracts${qs}`);
+  const contracts = data.contracts ?? [];
+
+  if (contracts.length === 0) {
+    return { contracts: [], total: 0, message: "No active contracts found. Create one with cascrow_create_contract or wait for invites via cascrow_check_invites." };
+  }
+
+  const lines = contracts.map((c) => {
+    const roleLabel = c.role === "requester" ? "Requester" : "Builder";
+    const activeMilestone = c.milestones.find((m) => ["FUNDED", "PROOF_SUBMITTED", "PENDING_REVIEW"].includes(m.status))
+      ?? c.milestones[0];
+    const msLine = activeMilestone
+      ? ` — milestone: "${activeMilestone.title}" [${activeMilestone.status}]`
+      : "";
+    return `  - ${c.contractId} [${c.status}] (${roleLabel})${msLine}`;
+  }).join("\n");
+
+  return {
+    ...data,
+    message: `Found ${data.total} contract(s):\n${lines}\n\nUse cascrow_get_contract with a contractId for full details.`,
+  };
+}
+
+async function handleGetProofStatus({ proofId }) {
+  const data = await apiGet(`/api/agent/proof-status/${encodeURIComponent(proofId)}`);
+
+  if (data.pending) {
+    return {
+      ...data,
+      message: `Proof ${proofId} is still being processed by the AI. Poll again in a few seconds.`,
+    };
+  }
+
+  const decision = data.decision === "YES" ? "✅ APPROVED" : "❌ REJECTED";
+  const conf = data.confidence !== null ? ` (confidence: ${data.confidence}%)` : "";
+  const parts = [
+    `Proof ${proofId}: ${decision}${conf}`,
+    `Contract status: ${data.contractStatus}`,
+    data.milestoneTitle ? `Milestone: "${data.milestoneTitle}" [${data.milestoneStatus}]` : null,
+    data.reasoning ? `Reasoning: ${data.reasoning.slice(0, 200)}${data.reasoning.length > 200 ? "…" : ""}` : null,
+  ].filter(Boolean);
+
+  return {
+    ...data,
+    message: parts.join("\n"),
+  };
+}
+
+async function handleMcpSubmit({ contract_id, milestone_id, evidence }) {
+  const data = await apiPost("/api/mcp/submit", { contract_id, milestone_id, evidence });
+
+  const verdict = data.verdict ?? "unknown";
+  const confidence = data.confidence ?? 0;
+  const onChainUrl = data.on_chain_url ?? null;
+  const proofId = data.proof_id ?? null;
+
+  let statusLine;
+  if (verdict === "approved") {
+    statusLine = `✅ APPROVED (${confidence}% confidence)${onChainUrl ? ` — proof: ${onChainUrl}` : ""}`;
+  } else if (verdict === "pending_review") {
+    statusLine = `⏳ PENDING_REVIEW (${confidence}% confidence) — manual review triggered.`;
+  } else {
+    statusLine = `❌ REJECTED (${confidence}% confidence) — resubmit with stronger evidence.`;
+  }
+
+  const votes = Array.isArray(data.model_votes) ? data.model_votes : [];
+  const voteSummary = votes
+    .map((v) => `  ${v.decision === "YES" ? "✅" : "❌"} ${v.model}: ${v.decision} (${v.confidence}%)`)
+    .join("\n");
+
+  return {
+    verdict,
+    confidence,
+    reasoning: data.reasoning ?? "",
+    model_votes: votes,
+    on_chain_url: onChainUrl,
+    proof_id: proofId,
+    signed_at: data.signed_at ?? null,
+    message: `${statusLine}${voteSummary ? `\n\n${voteSummary}` : ""}${data.reasoning ? `\n\n${data.reasoning.slice(0, 400)}` : ""}`,
+  };
+}
+
 // ─── MCP Server ───────────────────────────────────────────────────────────────
 
 const server = new Server(
-  { name: "cascrow", version: "1.1.5" },
+  { name: "cascrow", version: "1.4.0" },
   { capabilities: { tools: {} } }
 );
 
@@ -498,8 +829,14 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       case "cascrow_get_contract":     result = await handleGetContract(args);     break;
       case "cascrow_join_contract":    result = await handleJoinContract(args);    break;
       case "cascrow_handoff":          result = await handleHandoff(args);         break;
-      case "cascrow_check_invites":    result = await handleCheckInvites();        break;
-      case "cascrow_get_agent_id":     result = await handleGetAgentId();          break;
+      case "cascrow_check_invites":    result = await handleCheckInvites();              break;
+      case "cascrow_get_agent_id":     result = await handleGetAgentId();               break;
+      case "cascrow_get_reputation":   result = await handleGetReputation(args);        break;
+      case "cascrow_discover_agents":  result = await handleDiscoverAgents(args);       break;
+      case "cascrow_set_discoverable":  result = await handleSetDiscoverable(args);      break;
+      case "cascrow_list_my_contracts": result = await handleListMyContracts(args);      break;
+      case "cascrow_get_proof_status":  result = await handleGetProofStatus(args);       break;
+      case "cascrow_mcp_submit":        result = await handleMcpSubmit(args);            break;
       default:
         throw new Error(`Unknown tool: ${name}`);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cascrow-mcp",
-  "version": "1.1.5",
+  "version": "1.4.0",
   "description": "MCP server for Cascrow — agentic escrow and verification",
   "type": "module",
   "main": "index.js",