cascrow-mcp 1.1.4 → 1.1.6

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

@@ -67,16 +67,26 @@ async function uploadProof(milestoneId, filename, content) {
   return data;
 }
 
+// Stream verify with 180s timeout to handle slow AI quorums
 async function streamVerify(proofId) {
-  const res = await fetch(`${BASE_URL}/api/verify`, {
-    method: "POST",
-    headers: {
-      "Authorization": `Bearer ${API_KEY}`,
-      "Content-Type": "application/json",
-      "Accept": "text/event-stream",
-    },
-    body: JSON.stringify({ proofId }),
-  });
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), 180_000);
+
+  let res;
+  try {
+    res = await fetch(`${BASE_URL}/api/verify`, {
+      method: "POST",
+      headers: {
+        "Authorization": `Bearer ${API_KEY}`,
+        "Content-Type": "application/json",
+        "Accept": "text/event-stream",
+      },
+      body: JSON.stringify({ proofId }),
+      signal: controller.signal,
+    });
+  } finally {
+    clearTimeout(timeout);
+  }
 
   if (!res.ok) {
     const data = await res.json().catch(() => ({}));
@@ -88,36 +98,40 @@ async function streamVerify(proofId) {
   const decoder = new TextDecoder();
   let buffer = "";
 
-  while (true) {
-    const { done, value } = await reader.read();
-    if (done) break;
-    buffer += decoder.decode(value, { stream: true });
-
-    const lines = buffer.split("\n");
-    buffer = lines.pop() ?? "";
-
-    for (const line of lines) {
-      if (!line.startsWith("data:")) continue;
-      const raw = line.slice(5).trim();
-      if (!raw) continue;
-      try {
-        const msg = JSON.parse(raw);
-        if (msg.type === "model_vote") {
-          votes.push(msg);
-          // Log each vote to stderr so Claude Desktop can show live progress
-          const icon = msg.decision === "YES" ? "✅" : "❌";
-          process.stderr.write(`[cascrow] ${icon} ${msg.model}: ${msg.decision} (${msg.confidence}%)\n`);
-        } else if (msg.type === "complete") {
-          return { ...msg, votes };
-        } else if (msg.type === "error") {
-          throw new Error(msg.message);
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      buffer += decoder.decode(value, { stream: true });
+
+      const lines = buffer.split("\n");
+      buffer = lines.pop() ?? "";
+
+      for (const line of lines) {
+        if (!line.startsWith("data:")) continue;
+        const raw = line.slice(5).trim();
+        if (!raw) continue;
+        try {
+          const msg = JSON.parse(raw);
+          if (msg.type === "model_vote") {
+            votes.push(msg);
+            const icon = msg.decision === "YES" ? "✅" : "❌";
+            process.stderr.write(`[cascrow] ${icon} ${msg.model}: ${msg.decision} (${msg.confidence}%)\n`);
+          } else if (msg.type === "complete") {
+            return { ...msg, votes };
+          } else if (msg.type === "error") {
+            throw new Error(msg.message);
+          }
+        } catch (e) {
+          if (e instanceof SyntaxError) continue;
+          throw e;
         }
-      } catch (e) {
-        if (e instanceof SyntaxError) continue;
-        throw e;
       }
     }
+  } finally {
+    reader.cancel().catch(() => {});
   }
+
   throw new Error("Stream ended without a complete event");
 }
 
@@ -141,15 +155,11 @@ const TOOLS = [
           description: "List of milestones to verify",
           items: {
             type: "object",
-            required: ["title", "description", "deadlineDays"],
+            required: ["title", "deadlineDays"],
             properties: {
               title: {
                 type: "string",
-                description: "Short milestone title, e.g. 'Hero section with CTA'",
-              },
-              description: {
-                type: "string",
-                description: "Detailed acceptance criteria — what exactly must be true for this milestone to pass AI verification",
+                description: "Milestone title including acceptance criteria, e.g. 'Hero section with CTA — must be responsive down to 320px, LCP < 2s'",
               },
               deadlineDays: {
                 type: "number",
@@ -203,7 +213,9 @@ const TOOLS = [
       "Submit proof of completion for a milestone. " +
       "Write a detailed, specific proof report describing exactly what was built, " +
       "with verifiable evidence (URLs, metrics, specific implementation details). " +
-      "The more specific and verifiable the proof, the higher the AI confidence score.",
+      "The more specific and verifiable the proof, the higher the AI confidence score. " +
+      "NOTE: After submitting, the backend automatically triggers AI verification. " +
+      "You can call cascrow_verify afterwards to stream the live results.",
     inputSchema: {
       type: "object",
       required: ["milestoneId", "proof"],
@@ -223,10 +235,11 @@ const TOOLS = [
   {
     name: "cascrow_verify",
     description:
-      "Trigger AI verification for a submitted proof and wait for the result. " +
+      "Stream live AI verification results for a submitted proof. " +
       "5 AI models vote in parallel (Claude, GPT-4o, Gemini, Mistral, Cerebras). " +
-      "Returns decision (YES/NO), confidence score, reasoning, and action taken. " +
-      "Call this after cascrow_submit_proof.",
+      "Returns decision, confidence score, action (VERIFIED/PENDING_REVIEW/REJECTED), and per-model votes. " +
+      "Call this after cascrow_submit_proof to get live results. " +
+      "Confidence > 85 + YES = VERIFIED. Confidence 60–85 = PENDING_REVIEW (manual review needed). Confidence < 60 = REJECTED.",
     inputSchema: {
       type: "object",
       required: ["proofId"],
@@ -235,6 +248,17 @@ const TOOLS = [
       },
     },
   },
+  {
+    name: "cascrow_get_contract",
+    description: "Get the current status and details of a contract, including all milestones and their statuses.",
+    inputSchema: {
+      type: "object",
+      required: ["contractId"],
+      properties: {
+        contractId: { type: "string" },
+      },
+    },
+  },
   {
     name: "cascrow_join_contract",
     description:
@@ -252,17 +276,6 @@ const TOOLS = [
       },
     },
   },
-  {
-    name: "cascrow_get_contract",
-    description: "Get the current status and details of a contract, including all milestones.",
-    inputSchema: {
-      type: "object",
-      required: ["contractId"],
-      properties: {
-        contractId: { type: "string" },
-      },
-    },
-  },
   {
     name: "cascrow_handoff",
     description:
@@ -306,24 +319,28 @@ const TOOLS = [
 async function handleCreateContract({ milestones }) {
   const deadline = (days) => {
     const d = new Date();
-    d.setDate(d.getDate() + days);
+    d.setDate(d.getDate() + (days ?? 7));
     return d.toISOString();
   };
 
   const payload = {
     milestones: milestones.map((m) => ({
-      title: `${m.title} — ${m.description}`,
+      title: m.title,
       amountUSD: m.amountUSD ?? 0,
-      cancelAfter: deadline(m.deadlineDays ?? 7),
+      cancelAfter: deadline(m.deadlineDays),
     })),
   };
 
   const data = await apiPost("/api/contracts", payload);
   const contractUrl = `${BASE_URL}/contract/${data.contractId}`;
 
+  // API returns inviteLink — expose as both keys so callers can use either
+  const inviteCode = data.inviteLink ?? null;
+
   return {
     contractId: data.contractId,
-    inviteCode: data.inviteLink,
+    inviteCode,
+    inviteLink: inviteCode,
     contractUrl,
     milestoneCount: milestones.length,
     message: `Contract created with ${milestones.length} milestone(s). View it here: ${contractUrl}`,
@@ -361,7 +378,7 @@ async function handleSubmitProof({ milestoneId, proof, filename }) {
   );
   return {
     proofId: data.proofId,
-    message: `Proof submitted. Use cascrow_verify with proofId: ${data.proofId}`,
+    message: `Proof submitted (proofId: ${data.proofId}). AI verification has been triggered automatically. Call cascrow_verify with this proofId to stream the live results.`,
   };
 }
 
@@ -373,7 +390,10 @@ async function handleVerify({ proofId }) {
   const reasoning  = result.reasoning ?? "";
   const votes      = result.votes ?? [];
 
-  const passed = decision === "YES" && confidence >= 85;
+  // Mirror backend three-tier logic exactly:
+  // > 85 + YES = VERIFIED, 60–85 = PENDING_REVIEW, < 60 = REJECTED
+  const passed = action === "VERIFIED";
+  const pendingReview = action === "PENDING_REVIEW";
 
   const TOTAL_MODELS = 5;
   const yesCount = votes.filter((v) => v.decision === "YES").length;
@@ -384,26 +404,39 @@ async function handleVerify({ proofId }) {
     .join("\n");
   const failedNote = failedCount > 0 ? `\n  ⚠️ ${failedCount} model(s) failed to respond` : "";
   const voteHeader = votes.length > 0
-    ? `${yesCount}/${TOTAL_MODELS} models approved (${failedCount > 0 ? `${failedCount} failed` : "all responded"}):\n${voteSummary}${failedNote}\n\n`
+    ? `${yesCount}/${TOTAL_MODELS} models approved:\n${voteSummary}${failedNote}\n\n`
     : "";
 
+  let statusLine;
+  if (passed) {
+    statusLine = `✅ VERIFIED (${confidence}% confidence)`;
+  } else if (pendingReview) {
+    statusLine = `⏳ PENDING_REVIEW (${confidence}% confidence) — manual review required. Resubmit stronger proof or contact hello@cascrow.com.`;
+  } else {
+    statusLine = `❌ REJECTED (${confidence}% confidence) — resubmit with stronger proof.`;
+  }
+
   return {
     decision,
     confidence,
     action,
-    reasoning,
     passed,
+    pendingReview,
+    reasoning,
     totalModels: TOTAL_MODELS,
     modelsResponded: votes.length,
     modelsFailed: failedCount,
     txHash: result.txHash ?? null,
     modelVotes: votes.map((v) => ({ model: v.model, decision: v.decision, confidence: v.confidence })),
-    message: passed
-      ? `✅ VERIFIED — Cascrow consensus confidence: ${confidence}%\n\n${voteHeader}${reasoning.slice(0, 300)}`
-      : `❌ NOT VERIFIED — Cascrow consensus confidence: ${confidence}%\n\n${voteHeader}${reasoning.slice(0, 300)}`,
+    message: `${statusLine}\n\n${voteHeader}${reasoning.slice(0, 400)}`,
   };
 }
 
+async function handleGetContract({ contractId }) {
+  const data = await apiGet(`/api/contracts/${contractId}`);
+  return data;
+}
+
 async function handleJoinContract({ inviteCode }) {
   const data = await apiPost("/api/contracts/join", { inviteCode });
   return {
@@ -412,11 +445,6 @@ async function handleJoinContract({ inviteCode }) {
   };
 }
 
-async function handleGetContract({ contractId }) {
-  const data = await apiGet(`/api/contracts/${contractId}`);
-  return data;
-}
-
 async function handleHandoff({ inviteCode, builderAgentId, contractId, message }) {
   const data = await apiPost("/api/agent/handoff", { inviteCode, builderAgentId, contractId, message });
   return {
@@ -448,7 +476,7 @@ async function handleCheckInvites() {
 // ─── MCP Server ───────────────────────────────────────────────────────────────
 
 const server = new Server(
-  { name: "cascrow", version: "1.0.0" },
+  { name: "cascrow", version: "1.1.5" },
   { capabilities: { tools: {} } }
 );
 
@@ -462,36 +490,16 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
   try {
     let result;
     switch (name) {
-      case "cascrow_create_contract":
-        result = await handleCreateContract(args);
-        break;
-      case "cascrow_fund_milestone":
-        result = await handleFundMilestone(args);
-        break;
-      case "cascrow_escrow_fund":
-        result = await handleEscrowFund(args);
-        break;
-      case "cascrow_submit_proof":
-        result = await handleSubmitProof(args);
-        break;
-      case "cascrow_verify":
-        result = await handleVerify(args);
-        break;
-      case "cascrow_join_contract":
-        result = await handleJoinContract(args);
-        break;
-      case "cascrow_get_contract":
-        result = await handleGetContract(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_create_contract":  result = await handleCreateContract(args);  break;
+      case "cascrow_fund_milestone":   result = await handleFundMilestone(args);   break;
+      case "cascrow_escrow_fund":      result = await handleEscrowFund(args);      break;
+      case "cascrow_submit_proof":     result = await handleSubmitProof(args);     break;
+      case "cascrow_verify":           result = await handleVerify(args);          break;
+      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;
       default:
         throw new Error(`Unknown tool: ${name}`);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cascrow-mcp",
-  "version": "1.1.4",
+  "version": "1.1.6",
   "description": "MCP server for Cascrow — agentic escrow and verification",
   "type": "module",
   "main": "index.js",
@@ -11,6 +11,6 @@
     "start": "node index.js"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.0.0"
+    "@modelcontextprotocol/sdk": "^1.15.0"
   }
 }