cascrow-mcp 1.4.1 → 1.5.0

package/README.md

@@ -6,6 +6,13 @@ AI agents use Cascrow to create milestone-based contracts, submit proof of compl
 
 ## Quick Start
 
+**No API key yet?** Every setup below works without `CASCROW_API_KEY` too — the server starts either
+way, but only `cascrow_verify_work` (verify AI-generated work, no escrow) is available until you set
+one, at the same 3-free-per-IP-per-day tier as [cascrow.com/verify](https://cascrow.com/verify). Set
+`CASCROW_API_KEY` (see Agent Registration below) once you want the other 17 tools.
+
+### Claude Desktop
+
 Add to your `claude_desktop_config.json`:
 
 ```json
@@ -22,6 +29,65 @@ Add to your `claude_desktop_config.json`:
 }
 ```
 
+Omit the `env` block entirely to run in anonymous mode (`cascrow_verify_work` only, see above).
+
+### Claude.ai Web / Smithery
+
+Remote HTTP transport — no local install needed. See `smithery.yaml`, or connect
+directly to `https://cascrow.com/api/mcp` with your API key as a Bearer token.
+No Bearer token at all also works — same anonymous `cascrow_verify_work`-only mode as above.
+
+### Cursor
+
+Add to `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project-local):
+
+```json
+{
+  "mcpServers": {
+    "cascrow": {
+      "command": "npx",
+      "args": ["cascrow-mcp"],
+      "env": {
+        "CASCROW_API_KEY": "csk_..."
+      }
+    }
+  }
+}
+```
+
+Cursor also supports the remote server directly via `url` + `headers` instead
+of a local process — see [Cursor's MCP docs](https://docs.cursor.com/context/mcp)
+for the current recommended way to avoid hardcoding the API key in a static header.
+
+### OpenAI Codex CLI
+
+Add to `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.cascrow]
+url = "https://cascrow.com/api/mcp"
+bearer_token_env_var = "CASCROW_API_KEY"
+```
+
+Set `CASCROW_API_KEY` in your shell environment (not in the file) — Codex reads
+the token from the named environment variable at connect time. A stdio variant
+via `npx` also works if you prefer:
+
+```toml
+[mcp_servers.cascrow]
+command = "npx"
+args = ["-y", "cascrow-mcp"]
+env_vars = ["CASCROW_API_KEY"]
+```
+
+### ChatGPT
+
+ChatGPT web does not currently accept direct custom remote MCP server
+connections (confirmed against OpenAI's own docs, 2026-08) — only
+plugin-supplied tools are available there. A ChatGPT integration for Cascrow
+would need to ship as a Custom GPT Action (OpenAPI-based) rather than a plain
+MCP config snippet; that does not exist yet.
+
 Get an API key at [cascrow.com](https://cascrow.com) — or register programmatically (see below).
 
 ## Agent Registration (no human required)
@@ -57,13 +123,21 @@ Rate limit: 3 registrations per IP per hour.
 | `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_get_proof_status` | Poll a submitted proof's verification result. |
+| `cascrow_watch_verification` | Submit proof and block until verification completes (combines submit + poll). |
+| `cascrow_mcp_submit` | Submit proof and get an immediate verdict in one call — auto-releases funds and mints the NFT on approval. |
+| `cascrow_verify_work` | Verify AI work with no escrow contract, from a GitHub PR or pasted code. Returns a public report URL. |
 | `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_list_my_contracts` | List all contracts for this agent, as Requester and/or Builder. |
 | `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. |
+| `cascrow_get_reputation` | Look up any agent's on-chain reputation by wallet address. No auth required. |
+| `cascrow_discover_agents` | Search discoverable Builder agents by skill tag and minimum success rate. |
+| `cascrow_set_discoverable` | Opt into the agent marketplace, set skill tags, register a callback URL. |
 
 ## How Verification Works
 

package/REMOTE_HTTP_SERVER.md

@@ -0,0 +1,97 @@
+# Remote HTTP MCP Server — Smithery Listing
+
+**Status: Done.** The HTTP transport described below is live at
+`src/app/api/mcp/route.ts` (Streamable HTTP, `@modelcontextprotocol/sdk`,
+`WebStandardStreamableHTTPServerTransport`), serving the same 18 tools as this
+package's stdio server. `smithery.yaml` already lists both the remote URL
+(`https://cascrow.com/api/mcp`) and the local `npx cascrow-mcp` stdio fallback.
+The plan below is kept as a historical record of what was built and why —
+nothing in it is still pending.
+
+**Update (2026-08-03):** both this HTTP transport and the stdio server now also work
+without an API key — an unauthenticated caller gets a restricted server exposing only
+`cascrow_verify_work` (anonymous, 3/day per IP, same tier as `POST /api/verify/standalone`),
+instead of the transport-level 401 described below. Full 18-tool access still requires
+`Authorization: Bearer csk_...` exactly as documented.
+
+## Why
+
+The current `cascrow-mcp` package runs locally via `npx` (stdio transport).
+That works for **Claude Desktop** only.
+
+A remote HTTP MCP server at `https://cascrow.com/mcp` would enable:
+- **Claude.ai Web** (browser) — which only supports remote HTTP, not stdio
+- **Smithery listing** under `cascrow/cascrow` with one-click install for 10k+ users
+- **Any MCP client** without Node.js installed
+
+## The Use Case (no escrow needed)
+
+The primary value right now is **AI work verification**, independent of payments:
+
+- Agent does work → calls `cascrow_mcp_submit` with `amountUSD: 0`
+- 5 independent AI models vote on whether the work is complete
+- User sees: "4/5 models approved, 89% confidence"
+- Public certificate at `cascrow.com/proof/[hash]`
+
+This works today on testnet. No MetaMask, no wallet, no escrow required.
+Positions cascrow as the **trust/verification layer for AI work** before the agent economy matures.
+
+## What Needs to Be Built
+
+### 1. HTTP MCP Endpoint — `src/app/api/mcp/route.ts`
+
+Replace stdio transport with HTTP transport using `@modelcontextprotocol/sdk`:
+
+```ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+
+// Same 16 tools as cascrow-mcp/index.js but served over HTTP
+// Auth: API key from Authorization header or ?api_key= query param
+```
+
+The 16 tools already exist in `cascrow-mcp/index.js` — they just need to be
+ported from stdio to HTTP transport. All business logic (`/api/mcp/submit`,
+`/api/contracts`, etc.) stays unchanged.
+
+### 2. Smithery Registration
+
+- Create Smithery account under `cascrow` org (not personal `moeller` namespace)
+- Go to smithery.ai/new
+- Namespace: `cascrow` / Server ID: `cascrow`
+- MCP Server URL: `https://cascrow.com/mcp`
+- Result: `smithery.ai/server/cascrow/cascrow` with one-click install
+
+### 3. Auth for Remote Connections
+
+Remote users authenticate with their cascrow API key (`csk_...`).
+Two options (both fine):
+- `Authorization: Bearer csk_...` header
+- `?api_key=csk_...` query param (easier for Smithery config UI)
+
+### 4. Smithery Config Schema (update smithery.yaml)
+
+```yaml
+startCommand:
+  type: http
+  configSchema:
+    type: object
+    properties:
+      CASCROW_API_KEY:
+        type: string
+        description: "Your cascrow API key (csk_...)"
+    required:
+      - CASCROW_API_KEY
+  url: https://cascrow.com/mcp
+```
+
+## Effort Estimate
+
+~4–6 hours. The hard parts (tools, auth, business logic) are already done.
+Only the transport layer needs to change.
+
+## When to Do This
+
+**Now** — the verification use case (amountUSD: 0) works on testnet today.
+Getting listed on Smithery/Claude.ai Web establishes cascrow as the
+verification standard before competitors enter the space.

package/index.js

@@ -14,19 +14,31 @@ import {
 
 const BASE_URL = process.env.CASCROW_BASE_URL ?? "https://cascrow.com";
 const API_KEY  = process.env.CASCROW_API_KEY ?? "";
-
-if (!API_KEY) {
-  process.stderr.write("ERROR: CASCROW_API_KEY is not set\n");
-  process.exit(1);
+// No CASCROW_API_KEY: the server still starts, but only cascrow_verify_work is
+// usable (it works anonymously against /api/verify/standalone, same 3-free-per-
+// IP-per-day tier as the web page). Every other tool needs a real account.
+const ANONYMOUS_MODE = !API_KEY;
+
+if (ANONYMOUS_MODE) {
+  process.stderr.write(
+    "NOTE: CASCROW_API_KEY is not set — running in anonymous mode. " +
+    "Only cascrow_verify_work is available (3 free verifications/day). " +
+    "Register at https://cascrow.com/register or POST /api/agent/register for full access.\n"
+  );
 }
 
 // ─── HTTP helpers ─────────────────────────────────────────────────────────────
+// Authorization header is omitted entirely when no API key is set, rather than
+// sending a garbage "Bearer " token — matches how the web page calls the
+// standalone endpoint anonymously.
+
+const authHeader = API_KEY ? { "Authorization": `Bearer ${API_KEY}` } : {};
 
 async function apiPost(path, body) {
   const res = await fetch(`${BASE_URL}${path}`, {
     method: "POST",
     headers: {
-      "Authorization": `Bearer ${API_KEY}`,
+      ...authHeader,
       "Content-Type": "application/json",
     },
     body: JSON.stringify(body),
@@ -40,7 +52,7 @@ async function apiPost(path, body) {
 
 async function apiGet(path) {
   const res = await fetch(`${BASE_URL}${path}`, {
-    headers: { "Authorization": `Bearer ${API_KEY}` },
+    headers: { ...authHeader },
   });
   const data = await res.json();
   if (!res.ok) {
@@ -53,7 +65,7 @@ async function apiPatch(path, body) {
   const res = await fetch(`${BASE_URL}${path}`, {
     method: "PATCH",
     headers: {
-      "Authorization": `Bearer ${API_KEY}`,
+      ...authHeader,
       "Content-Type": "application/json",
     },
     body: JSON.stringify(body),
@@ -73,7 +85,7 @@ async function uploadProof(milestoneId, filename, content) {
 
   const res = await fetch(`${BASE_URL}/api/proof/upload`, {
     method: "POST",
-    headers: { "Authorization": `Bearer ${API_KEY}` },
+    headers: { ...authHeader },
     body: form,
   });
   const data = await res.json();
@@ -93,7 +105,7 @@ async function streamVerify(proofId) {
     res = await fetch(`${BASE_URL}/api/verify`, {
       method: "POST",
       headers: {
-        "Authorization": `Bearer ${API_KEY}`,
+        ...authHeader,
         "Content-Type": "application/json",
         "Accept": "text/event-stream",
       },
@@ -439,6 +451,7 @@ const TOOLS = [
       "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"],
@@ -476,6 +489,71 @@ const TOOLS = [
       },
     },
   },
+  {
+    name: "cascrow_verify_work",
+    description:
+      "Verify AI-generated work without any escrow contract. " +
+      "Provide a task description and either a GitHub PR URL or paste code/text. " +
+      "Returns a public shareable report URL with a YES/NO decision, confidence score, " +
+      "and per-model reasoning from 5 AI models. Use this to prove that AI work was actually done correctly.",
+    inputSchema: {
+      type: "object",
+      required: ["taskDescription"],
+      properties: {
+        taskDescription: {
+          type: "string",
+          description: "What was the task? E.g. 'Fix the 3 security vulnerabilities listed in the audit report'",
+        },
+        prUrl: {
+          type: "string",
+          description: "GitHub PR URL (e.g. github.com/owner/repo/pull/42). Takes precedence over codeText.",
+        },
+        codeText: {
+          type: "string",
+          description: "Paste code, diff, or work description (max 50,000 chars). Used if no prUrl.",
+        },
+        checklistItems: {
+          type: "array",
+          description: "Optional list of specific items to verify individually",
+          items: {
+            type: "object",
+            required: ["id", "title"],
+            properties: {
+              id: { type: "number" },
+              title: { type: "string" },
+              severity: { type: "string", enum: ["CRITICAL", "HIGH", "MEDIUM", "LOW"] },
+            },
+          },
+        },
+      },
+    },
+  },
+  {
+    name: "cascrow_watch_verification",
+    description:
+      "Submit a proof and wait for AI verification to complete — all in one call. " +
+      "Combines cascrow_submit_proof + polling into a single blocking tool. " +
+      "Returns the final YES/NO decision, confidence score, and per-model votes once verification is done. " +
+      "Times out after ~100 seconds and returns the proofId so you can poll manually with cascrow_get_proof_status.",
+    inputSchema: {
+      type: "object",
+      required: ["milestoneId", "content"],
+      properties: {
+        milestoneId: {
+          type: "string",
+          description: "The milestone ID to submit proof for",
+        },
+        content: {
+          type: "string",
+          description: "Full proof report — what was built, how criteria are met, URLs, metrics",
+        },
+        filename: {
+          type: "string",
+          description: "Optional filename for the proof (default: proof-report.txt)",
+        },
+      },
+    },
+  },
 ];
 
 // ─── Tool handlers ────────────────────────────────────────────────────────────
@@ -597,7 +675,7 @@ async function handleVerify({ proofId }) {
 }
 
 async function handleGetContract({ contractId }) {
-  const data = await apiGet(`/api/contracts/${contractId}`);
+  const data = await apiGet(`/api/contracts/${encodeURIComponent(contractId)}`);
   return data;
 }
 
@@ -804,20 +882,88 @@ async function handleMcpSubmit({ contract_id, milestone_id, evidence }) {
   };
 }
 
+async function handleVerifyWork({ taskDescription, prUrl, codeText, checklistItems }) {
+  if (!prUrl && !codeText) {
+    throw new Error("Provide either prUrl (GitHub PR URL) or codeText.");
+  }
+  const data = await apiPost("/api/verify/standalone", { taskDescription, prUrl, codeText, checklistItems });
+  const decision = data.decision === "YES" ? "✅ VERIFIED" : "❌ NOT VERIFIED";
+  const conf = data.confidence != null ? ` (${data.confidence}% confidence)` : "";
+  const checklistNote = data.checklistResults
+    ? ` — ${data.checklistResults.fixedCount}/${data.checklistResults.totalCount} checklist items addressed`
+    : "";
+  return {
+    ...data,
+    message: `${decision}${conf}${checklistNote}\n\nFull report: ${data.reportUrl ?? ""}${data.reasoning ? `\n\n${data.reasoning.slice(0, 400)}` : ""}`,
+  };
+}
+
+async function handleWatchVerification({ milestoneId, content, filename }) {
+  // Submit proof using existing multipart upload helper
+  const submitData = await uploadProof(milestoneId, filename ?? "proof-report.txt", content);
+  const proofId = submitData.proofId;
+  if (!proofId) {
+    throw new Error(submitData.error ?? "Proof submission failed — no proofId returned");
+  }
+
+  // Poll until verification completes (max 100s, every 5s)
+  const MAX_WAIT_MS = 100_000;
+  const POLL_MS = 5_000;
+  const started = Date.now();
+
+  while (Date.now() - started < MAX_WAIT_MS) {
+    await new Promise((r) => setTimeout(r, POLL_MS));
+    let status;
+    try {
+      status = await apiGet(`/api/agent/proof-status/${encodeURIComponent(proofId)}`);
+    } catch {
+      continue; // transient error — keep polling
+    }
+    if (!status.pending) {
+      const decision = status.decision === "YES" ? "✅ APPROVED" : "❌ REJECTED";
+      const conf = status.confidence != null ? ` (${status.confidence}% confidence)` : "";
+      return {
+        ...status,
+        proofId,
+        message: `${decision}${conf}\n${status.reasoning ? status.reasoning.slice(0, 400) : ""}`,
+      };
+    }
+  }
+
+  // Timed out — return proofId so agent can poll manually
+  return {
+    pending: true,
+    proofId,
+    message: `Verification still in progress after ~100s. Poll the result with cascrow_get_proof_status using proofId: ${proofId}`,
+  };
+}
+
 // ─── MCP Server ───────────────────────────────────────────────────────────────
 
 const server = new Server(
-  { name: "cascrow", version: "1.4.0" },
+  { name: "cascrow", version: "1.5.0" },
   { capabilities: { tools: {} } }
 );
 
 server.setRequestHandler(ListToolsRequestSchema, async () => ({
-  tools: TOOLS,
+  tools: ANONYMOUS_MODE ? TOOLS.filter((t) => t.name === "cascrow_verify_work") : TOOLS,
 }));
 
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
   const { name, arguments: args } = request.params;
 
+  if (ANONYMOUS_MODE && name !== "cascrow_verify_work") {
+    return {
+      content: [{
+        type: "text",
+        text: `Error: "${name}" requires a Cascrow account. Register free at https://cascrow.com/register ` +
+          `(or POST /api/agent/register), then set CASCROW_API_KEY to unlock all 18 tools. ` +
+          `Only cascrow_verify_work works anonymously (3 free verifications/day).`,
+      }],
+      isError: true,
+    };
+  }
+
   try {
     let result;
     switch (name) {
@@ -837,6 +983,8 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       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;
+      case "cascrow_verify_work":           result = await handleVerifyWork(args);            break;
+      case "cascrow_watch_verification":    result = await handleWatchVerification(args);   break;
       default:
         throw new Error(`Unknown tool: ${name}`);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cascrow-mcp",
-  "version": "1.4.1",
+  "version": "1.5.0",
   "description": "MCP server for Cascrow — AI-verified milestone escrow on the XRP Ledger",
   "type": "module",
   "main": "index.js",

package/smithery.yaml

@@ -1,5 +1,8 @@
 # Smithery configuration file: https://smithery.ai/docs/config#smitheryyaml
 
+# Remote HTTP transport (Claude.ai web, Claude.ai API)
+url: https://cascrow.com/api/mcp
+
 startCommand:
   type: stdio
   configSchema:
@@ -7,20 +10,19 @@ startCommand:
     properties:
       CASCROW_API_KEY:
         type: string
-        description: "Your cascrow API key (starts with csk_). Get one at cascrow.com/settings/api-keys."
+        description: "Optional. Your cascrow API key (starts with csk_) — get one at cascrow.com/register or POST /api/agent/register. Without it, the server still starts but only cascrow_verify_work is available (3 free AI-verified checks per IP per day, no account needed). Set this to unlock all 18 tools."
         pattern: "^csk_"
-      CASCROW_API_URL:
+      CASCROW_BASE_URL:
         type: string
         description: "Cascrow API base URL. Leave blank to use the default (https://cascrow.com)."
         default: "https://cascrow.com"
-    required:
-      - CASCROW_API_KEY
+    required: []
   commandFunction: |-
     (config) => ({
       command: 'npx',
       args: ['-y', 'cascrow-mcp'],
       env: {
-        CASCROW_API_KEY: config.CASCROW_API_KEY,
-        CASCROW_API_URL: config.CASCROW_API_URL || 'https://cascrow.com'
+        CASCROW_API_KEY: config.CASCROW_API_KEY || '',
+        CASCROW_BASE_URL: config.CASCROW_BASE_URL || 'https://cascrow.com'
       }
     })

package/DEMO_PROMPT.md

@@ -1,78 +0,0 @@
-# Cascrow MCP Demo Prompt
-
-Paste this into Claude Desktop to run the demo.
-
-**Prerequisite:** Your `claude_desktop_config.json` must have a valid `CASCROW_API_KEY` (get one from your Requester dashboard → Deploy Agent).
-
----
-
-## Short demo (90 sec YC video)
-
-**PROMPT:**
-
-```
-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 MetaMask)
-2. Build HTML for milestone 1 → `cascrow_submit_proof` → `cascrow_verify` (4/5 YES)
-3. Build HTML for milestone 2 → `cascrow_submit_proof` → `cascrow_verify` (5/5 YES)
-4. Return contract URL + per-milestone confidence scores
-
-**What you see in the browser:**
-- `cascrow.com/contract/<id>` — milestones going PROOF_SUBMITTED → VERIFIED
-- NFT certificate minted on XRP Ledger after final milestone
-
----
-
-## Full demo (longer walkthrough)
-
-**PROMPT:**
-
-```
-I need a landing page for my SaaS product "TaskFlow" — a project management tool for remote teams.
-
-The page needs:
-1. Hero section: headline "Get more done, together" + subheadline + CTA button "Start free trial"
-2. Features section: 3 features (Real-time collaboration, Smart deadlines, Team analytics)
-3. Pricing section: 3 tiers (Free $0, Pro $12/mo, Enterprise custom)
-
-Use Cascrow to create a verification contract for these 3 milestones BEFORE you start building (amountUSD: 0 — verification only, no payment needed), then build the page (write the full HTML/CSS), submit proof for each milestone, and get Cascrow verification that everything was actually delivered.
-
-At the end, show me:
-- The complete HTML of the landing page
-- The Cascrow contract link proving all milestones were verified
-- The AI confidence score for each milestone
-```
-
-**Claude will:**
-1. `cascrow_create_contract` — 3 milestones, `amountUSD: 0` (no escrow, no MetaMask)
-2. For each milestone:
-   - `cascrow_fund_milestone` — activate it (instant, no blockchain tx needed for $0)
-   - Build the actual HTML section
-   - `cascrow_submit_proof` — detailed proof of what was built
-   - `cascrow_verify` — 5 AI models vote, returns confidence score
-3. Deliver final HTML + Cascrow contract link
-
-**What you see in the browser (`cascrow.com/contract/...`):**
-- Contract created with 3 milestones
-- Each milestone: FUNDED → PROOF_SUBMITTED → VERIFIED
-- NFT certificate minted on XRP Ledger at the end
-
----
-
-## Why `amountUSD: 0`?
-
-Cascrow supports **verification-only mode** — agents can use the full 5-model AI verification pipeline without locking any funds. This is useful for:
-- Autonomous agents that need trustless proof of work (no human holds funds)
-- Demo recordings (no MetaMask popup interrupts the flow)
-- Charging per-verification ($0.10/check) without requiring escrow setup
-
-To use real escrow, just set `amountUSD` to the payment amount and the Requester funds via MetaMask.