cyberdyne-mcp 0.4.0

package/src/server.ts

@@ -0,0 +1,290 @@
+#!/usr/bin/env node
+/**
+ * CYBERDYNE MCP server — the agent gateway (LIVE).
+ *
+ * Exposes the CYBERDYNE marketplace to any MCP-capable agent (Claude, etc.) as
+ * tools that call the REAL platform API. There is NO in-memory state any more —
+ * every tool is a thin, typed wrapper over an HTTP endpoint on the live backend.
+ *
+ *   list_categories  — the static task taxonomy (no network)
+ *   search_humans    — POST /api/a2a {search_humans}      → capability index
+ *   get_treasury     — GET  /api/treasury                 → the agent's balance
+ *   fund_treasury    — POST /api/treasury/fund            → demo top-up (testnet only)
+ *   get_deposit_address — GET  /api/treasury/deposit      → where to send real USDC (live)
+ *   deposit          — POST /api/treasury/deposit         → credit treasury from a real USDC tx
+ *   post_task        — POST /api/tasks                    → open a task
+ *   assign_task      — POST /api/tasks/[id]/assign        → pick a human (→ authIntent)
+ *   authorize_task   — POST /api/tasks/[id]/authorize     → open the escrow hold
+ *   get_task         — GET  /api/tasks/[id]               → status + submissions/claims
+ *   release_payment  — POST /api/tasks/[id]/release       → capture (pay) or reject
+ *   close_task       — POST /api/tasks/[id]/close         → close a (multi-unit) bounty
+ *
+ * Auth: every networked tool sends the agent's `cyb_…` key. The REST routes take
+ * it as `Authorization: Bearer …`; search_humans goes through the a2a JSON-RPC
+ * gateway (the REST GET /api/humans is session-only), which carries the key as
+ * `identity_token`.
+ *
+ * The HUMAN submit-proof step happens in the app/UI (human-only — agents cannot
+ * submit on a human's behalf). So an agent's end-to-end flow is:
+ *   (live: get_deposit_address → send USDC → deposit) → post_task
+ *     → (humans claim, or assign_task picks one)
+ *     → assign_task → authorize_task (open the hold)
+ *     → poll get_task until a submission appears
+ *     → release_payment (approve → capture; else reject → refund)
+ *
+ * Config comes from the environment (see src/client.ts):
+ *   CYBERDYNE_API_URL         default "https://app.cyberdyne-os.xyz"
+ *   CYBERDYNE_IDENTITY_TOKEN  the agent's cyb_ key (required for networked tools)
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { CATEGORIES, TASK_CATEGORIES } from "./registry.js";
+import { ApiError, CyberdyneClient, MissingTokenError, readConfig } from "./client.js";
+
+const config = readConfig();
+const client = new CyberdyneClient(config);
+
+// ---- Result helpers -------------------------------------------------------
+
+const json = (data: unknown) => ({
+  content: [{ type: "text" as const, text: JSON.stringify(data, null, 2) }],
+});
+const err = (message: string) => ({
+  content: [{ type: "text" as const, text: JSON.stringify({ error: message }, null, 2) }],
+  isError: true,
+});
+
+/** Run a tool body, mapping client errors to a clean MCP error result. */
+async function guard<T>(fn: () => Promise<T>) {
+  try {
+    return json(await fn());
+  } catch (e) {
+    if (e instanceof MissingTokenError) return err(e.message);
+    if (e instanceof ApiError) return err(e.message);
+    return err(e instanceof Error ? e.message : String(e));
+  }
+}
+
+// ---- Server ---------------------------------------------------------------
+
+const server = new McpServer({ name: "cyberdyne", version: "0.2.0" });
+
+server.tool(
+  "list_categories",
+  "List the kinds of real-world work CYBERDYNE humans can do. Static (no network). Use this to learn the valid `category` values before posting a task.",
+  {},
+  async () => json(Object.entries(CATEGORIES).map(([id, blurb]) => ({ id, blurb }))),
+);
+
+server.tool(
+  "search_humans",
+  "Find verified humans by capability via the live capability index (a2a gateway). Filters are optional and combine (AND). Results are role='human' profiles ranked by reputation, projected to public columns (no wallets/balances). Note: `skills` is an array.",
+  {
+    skills: z
+      .array(z.enum(TASK_CATEGORIES))
+      .optional()
+      .describe("Task categories the human must be able to do (all must match)."),
+    min_reputation: z.number().min(0).max(5).optional().describe("Minimum reputation (0–5)."),
+    location: z.string().optional().describe("Substring match on location, e.g. 'ES', 'Tokyo'."),
+  },
+  async ({ skills, min_reputation, location }) =>
+    guard(() =>
+      client.a2a<{ humans: unknown[] }>("search_humans", {
+        ...(skills ? { skills } : {}),
+        ...(min_reputation != null ? { min_reputation } : {}),
+        ...(location ? { location } : {}),
+      }),
+    ),
+);
+
+server.tool(
+  "get_treasury",
+  "Get the agent's own treasury (the source of task rewards on the manual rail). Returns null if the agent has no treasury yet — call fund_treasury to create one.",
+  {},
+  async () => guard(() => client.rest("GET", "/api/treasury")),
+);
+
+server.tool(
+  "fund_treasury",
+  "Demo top-up (TESTNET/DEMO ONLY): add USD to the treasury balance. DISABLED when the platform is live (returns 403 funding_disabled) — on the live rail fund with REAL USDC via get_deposit_address + deposit instead.",
+  { amount_usd: z.number().positive().describe("USD to add to the treasury balance.") },
+  async ({ amount_usd }) =>
+    guard(() => client.rest("POST", "/api/treasury/fund", { body: { amount_usd } })),
+);
+
+server.tool(
+  "get_deposit_address",
+  "Get the on-chain address to fund your treasury with REAL USDC (live rail). Returns { deposit_address, chain_id, usdc_address, decimals }. Send USDC from your VERIFIED wallet to deposit_address on Base, then call `deposit` with the tx hash to credit your treasury.",
+  {},
+  async () => guard(() => client.rest("GET", "/api/treasury/deposit")),
+);
+
+server.tool(
+  "deposit",
+  "Credit your treasury from a REAL on-chain USDC deposit (live rail; the real-money replacement for fund_treasury). First send USDC to the address from get_deposit_address (from your verified wallet), then call this with the transaction hash. The transfer is verified on-chain (to = platform wallet, from = your wallet) and credited exactly once — resubmitting the same tx never double-credits.",
+  {
+    tx_hash: z
+      .string()
+      .regex(/^0x[0-9a-fA-F]{64}$/)
+      .describe("The Base tx hash of your USDC transfer to the deposit address."),
+  },
+  async ({ tx_hash }) =>
+    guard(() => client.rest("POST", "/api/treasury/deposit", { body: { tx_hash } })),
+);
+
+server.tool(
+  "post_task",
+  "Open a task on the marketplace. Funds are NOT charged at post — the escrow hold opens later at authorize_task. On the manual rail the platform only checks the treasury can cover the budget (402 insufficient_treasury otherwise). `reward_usd` is the total budget; with quantity>1 each unit holds reward_usd/quantity. Returns the created task (with its id).",
+  {
+    title: z.string().min(2).max(160).describe("Short task title."),
+    category: z.enum(TASK_CATEGORIES),
+    description: z.string().max(4000).optional().describe("What you need the human to do."),
+    steps: z.array(z.string()).optional().describe("Ordered steps / acceptance criteria."),
+    reward_usd: z.number().positive().describe("Total reward budget in USD."),
+    quantity: z.number().int().positive().optional().describe("Number of identical units (default 1)."),
+    duration_min: z.number().int().positive().describe("Estimated minutes to complete."),
+    difficulty: z.enum(["easy", "medium", "hard"]),
+    pay_token: z.enum(["USDC", "BNKR", "CYOS"]).optional().describe("Settlement token (default USDC)."),
+    deadline_hours: z.number().int().positive().optional(),
+  },
+  async (args) => guard(() => client.rest("POST", "/api/tasks", { body: args })),
+);
+
+server.tool(
+  "assign_task",
+  "Assign an open task to a chosen human (poster-only) and open the escrow intent. Returns `{ task, authIntent }`: on an on-chain rail `authIntent` is the auth-capture requirements the agent must sign; on the manual rail it is null. Next call authorize_task to actually open the hold.",
+  {
+    task_id: z.string().uuid(),
+    human_id: z.string().uuid().describe("The human profile id (from search_humans / get_task claims)."),
+  },
+  async ({ task_id, human_id }) =>
+    guard(() => client.rest("POST", `/api/tasks/${task_id}/assign`, { body: { human_id } })),
+);
+
+server.tool(
+  "authorize_task",
+  "Open the escrow hold for an assigned task (poster-only). On the manual rail the body is empty (logical treasury debit). On an on-chain rail pass `signed_payment` — the base64 agent-signed auth-capture payload from the authIntent returned by assign_task. Idempotent once held.",
+  {
+    task_id: z.string().uuid(),
+    signed_payment: z
+      .string()
+      .optional()
+      .describe("On-chain rail only: base64-encoded signed auth-capture payload."),
+  },
+  async ({ task_id, signed_payment }) =>
+    guard(() =>
+      client.rest("POST", `/api/tasks/${task_id}/authorize`, {
+        body: signed_payment ? { signedPayment: signed_payment } : {},
+      }),
+    ),
+);
+
+server.tool(
+  "get_task",
+  "Get the live state of a task: the task row plus the submissions and per-unit claims the agent (as poster) may see. Poll this after authorize_task until a submission with status 'pending' appears — that is the human's proof, ready for release_payment.",
+  { task_id: z.string().uuid() },
+  async ({ task_id }) => guard(() => client.rest("GET", `/api/tasks/${task_id}`)),
+);
+
+server.tool(
+  "release_payment",
+  "Settle a submitted proof (poster-only). approve:true → CAPTURE: pay the human net of platform fee. approve:false → REJECT/REFUND the held escrow. Requires the `submission_id` to act on; if omitted, the gateway fetches the task and uses the latest pending submission (and errors if none is pending yet — poll get_task first).",
+  {
+    task_id: z.string().uuid(),
+    approve: z.boolean().describe("true = proof meets criteria → pay; false = reject/refund."),
+    submission_id: z
+      .string()
+      .uuid()
+      .optional()
+      .describe("The submission to settle. Auto-resolved to the latest pending one if omitted."),
+    score: z.number().int().min(1).max(5).optional().describe("Rating of the human's work (1–5)."),
+    reject_reason: z.string().max(1000).optional().describe("Why the proof was rejected (approve:false)."),
+  },
+  async ({ task_id, approve, submission_id, score, reject_reason }) =>
+    guard(async () => {
+      // The release endpoint settles a specific submission. If the caller didn't
+      // pass one, resolve the latest PENDING submission from the live task.
+      let sid = submission_id;
+      if (!sid) {
+        const detail = await client.rest<{ submissions?: Array<{ id: string; status: string }> }>(
+          "GET",
+          `/api/tasks/${task_id}`,
+        );
+        const pending = (detail.submissions ?? []).find((s) => s.status === "pending");
+        if (!pending) {
+          throw new ApiError(
+            409,
+            "no_pending_submission (poll get_task until the human submits proof)",
+            `GET /api/tasks/${task_id}`,
+          );
+        }
+        sid = pending.id;
+      }
+      return client.rest("POST", `/api/tasks/${task_id}/release`, {
+        body: {
+          submission_id: sid,
+          approve,
+          ...(score != null ? { score } : {}),
+          ...(reject_reason ? { reject_reason } : {}),
+        },
+      });
+    }),
+);
+
+server.tool(
+  "close_task",
+  "Close a (multi-unit) bounty (poster-only): refund every still-held unit to the agent, mark unclaimed units done, and stop further claims. Idempotent on an already-closed task.",
+  { task_id: z.string().uuid() },
+  async ({ task_id }) => guard(() => client.rest("POST", `/api/tasks/${task_id}/close`)),
+);
+
+// ---- Self-onboarding prompt -----------------------------------------------
+// Surfaces as /mcp__cyberdyne__quickstart — the agent (or user) runs it once to
+// learn the end-to-end campaign flow without reading docs. This is the "skill"
+// shipped inside the MCP: guidance travels with the tools.
+server.registerPrompt(
+  "quickstart",
+  {
+    title: "CYBERDYNE quickstart",
+    description: "How to fund, post a campaign, and pay humans end-to-end (live rail).",
+  },
+  () => ({
+    messages: [
+      {
+        role: "user",
+        content: {
+          type: "text",
+          text: [
+            "You are connected to CYBERDYNE — hire and pay verified humans for tasks AI can't do alone. Settlement is REAL USDC on Base.",
+            "",
+            "FUND (live rail, real money):",
+            "1. get_deposit_address → returns the platform deposit address on Base.",
+            "2. Send USDC to that address FROM your own verified wallet (the one you signed in with).",
+            "3. deposit({ tx_hash }) → credits your treasury by the verified amount (idempotent).",
+            "   (fund_treasury is demo-only and is disabled on the live rail.)",
+            "",
+            "RUN A CAMPAIGN:",
+            "4. post_task({ title, category, reward_usd, quantity, duration_min, difficulty }) — reward_usd is the TOTAL budget; with quantity>1 each unit holds reward_usd/quantity. Use reward_usd ≥ 0.50 so the 2.5% fee is visible.",
+            "5. Humans claim units and submit proof (the submit step is human-only, in the app — you cannot submit for them). Poll get_task until a submission is pending.",
+            "   - Or pick someone yourself: search_humans({ skills, min_reputation }) → assign_task({ task_id, human_id }) → authorize_task({ task_id }) to open the hold.",
+            "6. release_payment({ task_id, approve: true, score }) → captures: net USDC is paid to the human, the 2.5% fee goes to the protocol wallet. approve:false refunds the hold.",
+            "7. close_task({ task_id }) → refund any still-unclaimed units of a multi-unit bounty.",
+            "",
+            "Check get_treasury anytime for your balance. Every payout and fee is a real on-chain tx.",
+          ].join("\n"),
+        },
+      },
+    ],
+  }),
+);
+
+// ---- Boot -----------------------------------------------------------------
+
+const transport = new StdioServerTransport();
+await server.connect(transport);
+console.error(
+  `CYBERDYNE MCP server running on stdio → ${config.apiUrl}` +
+    (config.token ? "" : " (no CYBERDYNE_IDENTITY_TOKEN set; networked tools will error until you set it)") +
+    ". Tools: list_categories, search_humans, get_treasury, fund_treasury, get_deposit_address, deposit, post_task, assign_task, authorize_task, get_task, release_payment, close_task.",
+);

package/src/smoke.ts

@@ -0,0 +1,104 @@
+/**
+ * Live smoke test: drive the MCP server against the REAL platform API like an
+ * agent would. Not shipped.
+ *
+ * Requires both env vars to run for real:
+ *   CYBERDYNE_API_URL        e.g. http://localhost:3000 or https://app.cyberdyne-os.xyz
+ *   CYBERDYNE_IDENTITY_TOKEN the agent's cyb_ key
+ * If either is missing it no-ops with a clear message (no key is ever hardcoded).
+ *
+ * The server inherits this process's env over stdio, so the same creds drive it.
+ */
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+
+const apiUrl = process.env.CYBERDYNE_API_URL;
+const token = process.env.CYBERDYNE_IDENTITY_TOKEN;
+
+if (!token) {
+  console.log(
+    "smoke: no-op. Set CYBERDYNE_IDENTITY_TOKEN (a cyb_ key) and optionally " +
+      "CYBERDYNE_API_URL to run the live flow against the platform.\n" +
+      "  e.g. CYBERDYNE_API_URL=http://localhost:3000 CYBERDYNE_IDENTITY_TOKEN=cyb_… npm run smoke",
+  );
+  process.exit(0);
+}
+
+const transport = new StdioClientTransport({
+  command: "node",
+  args: ["dist/server.js"],
+  env: { ...process.env } as Record<string, string>,
+});
+const client = new Client({ name: "smoke", version: "0" });
+await client.connect(transport);
+
+const call = async (name: string, args: Record<string, unknown> = {}) => {
+  const r: any = await client.callTool({ name, arguments: args });
+  const data = JSON.parse(r.content[0].text);
+  if (r.isError) throw new Error(`${name} → ${data.error}`);
+  return data;
+};
+
+console.log(`smoke → ${apiUrl ?? "https://app.cyberdyne-os.xyz"}`);
+console.log("tools:", (await client.listTools()).tools.map((t) => t.name).join(", "));
+
+// 1. Categories (static, no network).
+const cats = await call("list_categories");
+console.log(`list_categories → ${cats.length} categories`);
+
+// 2. Treasury — ensure it can cover a small task; top up if needed.
+let treasury = await call("get_treasury");
+const balance = Number(treasury.treasury?.balance_usd ?? 0);
+console.log(`get_treasury → balance $${balance}`);
+if (balance < 5) {
+  treasury = await call("fund_treasury", { amount_usd: 25 });
+  console.log(`fund_treasury → balance $${treasury.treasury?.balance_usd}`);
+}
+
+// 3. Discover a human via the live capability index.
+const found = await call("search_humans", { skills: ["capture"] });
+console.log(`search_humans(capture) → ${found.humans.length} match`);
+const human = found.humans[0];
+
+// 4. Post a task. reward_usd is the budget; not charged until authorize.
+const posted = await call("post_task", {
+  title: "Read 10 phrases (smoke)",
+  category: "capture",
+  description: "Record 10 short phrases clearly in a quiet room.",
+  reward_usd: 3.5,
+  duration_min: 10,
+  difficulty: "easy",
+});
+const taskId = posted.task.id;
+console.log(`post_task → ${taskId} (status ${posted.task.status})`);
+
+// 5. If we found a human, assign + authorize (open the escrow hold).
+if (human?.id) {
+  const assigned = await call("assign_task", { task_id: taskId, human_id: human.id });
+  console.log(`assign_task → status ${assigned.task.status}, authIntent ${assigned.authIntent ? "present" : "null (manual rail)"}`);
+  const authd = await call("authorize_task", { task_id: taskId });
+  console.log(`authorize_task → escrow_status ${authd.task?.escrow_status}`);
+}
+
+// 6. Poll the live task. The human submits proof in the app (human-only), so on a
+//    fresh task there is typically no submission yet — that is expected here.
+const got = await call("get_task", { task_id: taskId });
+console.log(
+  `get_task → status ${got.task.status}, submissions ${got.submissions.length}, claims ${got.claims.length}`,
+);
+
+const pending = (got.submissions ?? []).find((s: any) => s.status === "pending");
+if (pending) {
+  const settled = await call("release_payment", { task_id: taskId, approve: true, score: 5 });
+  console.log(`release_payment → settled, task status ${settled.task?.status}`);
+} else {
+  console.log(
+    "release_payment → skipped: no pending submission yet (a human submits proof in the app). " +
+      "Closing the task to release the hold.",
+  );
+  const closed = await call("close_task", { task_id: taskId });
+  console.log(`close_task → status ${closed.task?.status}`);
+}
+
+await client.close();
+console.log("OK");