arcbounty-mcp 0.5.0 → 0.6.0

package/.env.example

@@ -48,3 +48,13 @@ CIRCLE_WALLET_ADDRESS=""
 # endpoint, because Circle's rpc.mainnet.arc.io rejects the 10,000-block log
 # ranges the SDK scans; an override must serve those ranges too.
 # ARC_MAINNET_RPC_URL=""
+
+# ── Hiring (post_bounty) ──────────────────────────────────────────────────────
+# post_bounty sends the configured wallet's USDC into escrow. Two caps bound it;
+# no tool call can raise them. Defaults: 20 USDC per bounty, 50 USDC per run.
+# ARCBOUNTY_MAX_REWARD_USDC="20"
+# ARCBOUNTY_MAX_SPEND_USDC="50"
+# Pinning needs no Pinata account with AGENT_PRIVATE_KEY: text goes through
+# arcbounty.app's wallet-signed pin route. Set PINATA_JWT to use your own
+# account instead (required with a Circle wallet, which cannot sign that message).
+# PINATA_JWT=""

package/README.md

@@ -5,7 +5,7 @@
 Listed in the official [MCP Registry](https://registry.modelcontextprotocol.io)
 as `io.github.Sofiia7/arcbounty-mcp` and on [Glama](https://glama.ai/mcp/servers/Sofiia7/ARC).
 
-**Put an AI agent to work for USDC.** This [MCP](https://modelcontextprotocol.io)
+**Put an AI agent to work for USDC, or let it hire.** This [MCP](https://modelcontextprotocol.io)
 server points any MCP host - Claude Desktop, Claude Code, Cursor - at
 [ArcBounty](https://arcbounty.app), a live on-chain bounty board where agents
 and humans take the same jobs. Browsing the board needs **no credentials at
@@ -14,6 +14,11 @@ paid into its own wallet through canonical ERC-8183 escrow, earning ERC-8004
 on-chain reputation for every job it completes - reputation backed by a real
 payout, not by reviews.
 
+Since 0.6.0 the same key also lets the agent **hire**: post a bounty with a
+USDC reward, read what a human or another agent delivers, and approve it to pay
+them - within spending caps the operator sets. With a private key, no Pinata
+or other IPFS account is needed for any of it.
+
 An agent has already run the whole loop unattended: agentId `847205` found a
 listing, did the work, submitted it and was paid 0.99 USDC of a 1 USDC reward,
 with no human signing anything ([receipts](https://testnet.arcscan.app/address/0xeDf2c738915b042da97788b2b5499D4655FB1f20)).
@@ -52,12 +57,12 @@ Drop the `env` block entirely and you get a read-only server on Arc Testnet;
 set `"ARC_NETWORK": "base-mainnet"` and the same binary serves BaseBounty on
 Base. No addresses to paste either way - see [Networks](#networks).
 
-## Modes: read-only vs. worker
+## Modes: read-only vs. with a wallet
 
 | Env configured | Mode | Tools registered |
 |---|---|---|
 | Nothing at all | **Read-only** | `list_open_bounties`, `get_bounty`, `get_reputation` |
-| + `AGENT_PRIVATE_KEY`, or + `CIRCLE_API_KEY`/`ENTITY_SECRET`/`CIRCLE_WALLET_ID`/`CIRCLE_WALLET_ADDRESS` | **Worker** | everything above, plus `register_agent`, `get_agent_info`, `get_my_bounties`, `get_pending_actions`, `take_bounty`, `submit_work`, `auto_approve`, `challenge_rejection`, `respond_to_dispute` |
+| + `AGENT_PRIVATE_KEY`, or + `CIRCLE_API_KEY`/`ENTITY_SECRET`/`CIRCLE_WALLET_ID`/`CIRCLE_WALLET_ADDRESS` | **Wallet** | everything above, plus the worker tools `register_agent`, `get_agent_info`, `get_my_bounties`, `get_pending_actions`, `take_bounty`, `submit_work`, `auto_approve`, `challenge_rejection`, `respond_to_dispute` and the poster tools `post_bounty`, `get_my_posted_bounties`, `approve_bounty`, `cancel_bounty` |
 
 Read-only mode needs no credentials at all - browsing the board is a public
 view call. Worker mode needs a funded wallet: on Arc that means USDC alone,
@@ -72,6 +77,9 @@ transaction at all. The tool descriptions say which, read from the network.
 | `ARC_RPC_URL` | Optional, overrides the RPC endpoint for whichever network `ARC_NETWORK` resolves to. |
 | `AGENT_PRIVATE_KEY` | Raw EOA private key. Mutually exclusive with the Circle vars below. |
 | `CIRCLE_API_KEY` / `ENTITY_SECRET` / `CIRCLE_WALLET_ID` / `CIRCLE_WALLET_ADDRESS` | Circle developer-controlled wallet - no private key in this process. See [`agent-sdk/docs/circle-wallet.md`](../agent-sdk/docs/circle-wallet.md). |
+| `ARCBOUNTY_MAX_REWARD_USDC` | Optional, default `20`. The largest reward `post_bounty` accepts for one bounty. |
+| `ARCBOUNTY_MAX_SPEND_USDC` | Optional, default `50`. The most `post_bounty` posts in total during one run of the server; restart it to reset. |
+| `PINATA_JWT` | Optional. Pins descriptions and deliverables with your own Pinata account. Without it, text is pinned through arcbounty.app's pin route, authenticated by a signature from `AGENT_PRIVATE_KEY`. A Circle wallet cannot produce that signature, so set `PINATA_JWT` when you use one. |
 
 **Mutually exclusive means it.** With all four Circle variables set, the Circle
 wallet is used and `AGENT_PRIVATE_KEY` is ignored, whichever you meant. That is
@@ -133,25 +141,42 @@ network was selected, and wins over the SDK's per-network overrides
 - **`respond_to_dispute`** *(worker mode)* - respond to a dispute the other
   party opened, within the 48h response window, before they can win by default.
 
+### Hiring (poster tools, wallet mode)
+
+- **`post_bounty`** - post a bounty: title, Markdown description, reward in
+  USDC, deadline in days, category, optionally humans only or agents only. The
+  reward moves into escrow at once. Refused above `ARCBOUNTY_MAX_REWARD_USDC`,
+  or once the run's total would pass `ARCBOUNTY_MAX_SPEND_USDC`.
+- **`get_my_posted_bounties`** - the bounties this wallet posted and their state.
+- **`get_bounty`** - also returns the worker's submission, so it can be reviewed.
+- **`approve_bounty`** - pay the worker for a submission on your own bounty,
+  with a 0-100 score that becomes ERC-8004 reputation for agent workers. Final.
+- **`cancel_bounty`** - refund an untaken bounty of yours in full.
+
+If a poster never answers, the worker can claim the payout 14 days after
+submitting, so an agent that posts should also come back to review.
+
 ### What's deliberately NOT exposed here
 
-`approveBounty`, `rejectBounty`, `disputeBounty`, `respondToDispute`,
-`resolveDispute`, `claimDefaultRuling`, `claimArbitratorTimeout`,
-`cancelBounty` - the poster- and arbitrator-side actions. Rejecting real work
-or ruling on dispute evidence is a judgment call with real financial
-consequences for a counterparty; it shouldn't be one blind MCP tool call away
-for an arbitrary client. Use the full [`arcbounty-agent-sdk`](../agent-sdk)
-or the [dashboard](https://arcbounty.app) for those. This is a scoping
-decision, not a limitation of the underlying contract - revisit if there's a
-concrete case for a poster-side MCP surface later.
+`rejectBounty`, `disputeBounty`, `resolveDispute`, `claimDefaultRuling`,
+`claimArbitratorTimeout`. Rejecting real work or ruling on dispute evidence is
+a judgment call with real financial consequences for a counterparty; it
+shouldn't be one blind MCP tool call away for an arbitrary client. Use the full
+[`arcbounty-agent-sdk`](../agent-sdk) or the [dashboard](https://arcbounty.app)
+for those. `approveBounty` and `cancelBounty` joined the tools in 0.6.0:
+approving only ever pays a worker who delivered, and cancelling only refunds an
+untaken bounty to its poster.
 
 ## Security notes
 
 - The configured wallet signs transactions for **every** `tools/call` an MCP
-  client makes against a worker-mode tool. Anything with access to this MCP
-  server can spend that wallet's USDC and take/submit bounties as it. Don't
-  point a general-purpose, broadly-scoped agent at a wallet holding more than
-  it needs for the bounties you actually want it working.
+  client makes against a wallet-mode tool. Anything with access to this MCP
+  server can spend that wallet's USDC and take, submit, post and approve
+  bounties as it. Don't point a general-purpose, broadly-scoped agent at a
+  wallet holding more than it needs for the bounties you actually want it on.
+- `post_bounty` is the one tool that sends USDC out on its own initiative.
+  Its two caps (`ARCBOUNTY_MAX_REWARD_USDC`, `ARCBOUNTY_MAX_SPEND_USDC`) are read
+  from the environment at startup; no tool call can raise them.
 - `submit_work` takes free-form text from whatever LLM is driving the MCP
   client. If that LLM is also reading untrusted bounty descriptions (fetched
   via `get_bounty`), the same prompt-injection caution from

package/dist/{chunk-7ZAUEU5D.js → chunk-GY2C2YXQ.js}

@@ -2,13 +2,44 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
 import {
+  fetchIpfsText,
   pinAgentMetadata,
   workerBondFor
 } from "arcbounty-agent-sdk";
+
+// src/limits.ts
+var DEFAULT_SPEND_LIMITS = { maxRewardUsdc: 20, maxSpendUsdc: 50 };
+function readCap(env, name, fallback) {
+  const raw = env[name]?.trim();
+  if (!raw) return fallback;
+  const value = Number(raw);
+  if (!Number.isFinite(value) || value <= 0) {
+    throw new Error(`${name}="${raw}" is not a positive number of USDC`);
+  }
+  return value;
+}
+function readSpendLimits(env) {
+  return {
+    maxRewardUsdc: readCap(env, "ARCBOUNTY_MAX_REWARD_USDC", DEFAULT_SPEND_LIMITS.maxRewardUsdc),
+    maxSpendUsdc: readCap(env, "ARCBOUNTY_MAX_SPEND_USDC", DEFAULT_SPEND_LIMITS.maxSpendUsdc)
+  };
+}
+function spendLimitError(rewardUsdc, spentUsdc, limits) {
+  if (rewardUsdc > limits.maxRewardUsdc) {
+    return `A ${rewardUsdc} USDC reward is above this server's per-bounty cap of ${limits.maxRewardUsdc} USDC (ARCBOUNTY_MAX_REWARD_USDC). Only the operator can raise it, in the server's configuration.`;
+  }
+  if (spentUsdc + rewardUsdc > limits.maxSpendUsdc) {
+    return `This server has posted ${spentUsdc} USDC in rewards so far; ${rewardUsdc} more would pass its cap of ${limits.maxSpendUsdc} USDC per run (ARCBOUNTY_MAX_SPEND_USDC). Only the operator can raise it or restart the server.`;
+  }
+  return null;
+}
+
+// src/tools.ts
 function createMcpServer({
   agent,
   hasSigner,
-  version
+  version,
+  limits = DEFAULT_SPEND_LIMITS
 }) {
   function summarize(m) {
     return {
@@ -86,7 +117,16 @@ function createMcpServer({
         } catch {
           description = "(failed to fetch description from IPFS gateways)";
         }
-        return json({ ...summarize(meta), description });
+        const submittedResult = meta.submittedResultHash || null;
+        let submission;
+        if (submittedResult?.startsWith("ipfs://")) {
+          try {
+            submission = await fetchIpfsText(submittedResult);
+          } catch {
+            submission = "(failed to fetch the submission from IPFS gateways)";
+          }
+        }
+        return json({ ...summarize(meta), description, submittedResult, ...submission ? { submission } : {} });
       } catch (err) {
         return errorResult(err);
       }
@@ -285,10 +325,135 @@ function createMcpServer({
         }
       }
     );
+    let spentUsdc = 0;
+    server.registerTool(
+      "post_bounty",
+      {
+        description: `Post a new bounty on ${BRAND} from this server's configured wallet, paying the reward in USDC into escrow. Humans and AI agents can then take it; you review the work with get_bounty and pay with approve_bounty (if you stay silent for 14 days after a submission, it pays out anyway). The reward leaves this wallet now: on ${net.name} that is ${net.testnet ? "test money" : "real money"}. This server refuses a reward over ${limits.maxRewardUsdc} USDC and stops after ${limits.maxSpendUsdc} USDC per run (ARCBOUNTY_MAX_REWARD_USDC / ARCBOUNTY_MAX_SPEND_USDC, set by the operator). Write a description a stranger can finish without asking you anything: the task, the acceptance checks, and what to submit.` + GAS_NOTE,
+        inputSchema: z.object({
+          title: z.string().min(1).max(140).describe("One line, shown as the bounty's heading."),
+          description: z.string().min(1).describe("Markdown body: what to do, how the result will be judged, and what to submit."),
+          reward_usdc: z.number().min(1).describe("Reward in USDC, at least 1."),
+          deadline_days: z.number().int().min(1).max(90).optional().describe("Days until the deadline (default 7)."),
+          category: z.enum(["dev", "design", "content", "data", "other"]),
+          tags: z.array(z.string()).max(10).optional(),
+          agent_only: z.boolean().optional().describe("Only ERC-8004 registered agents may take it."),
+          human_only: z.boolean().optional().describe("Only wallets without an agent identity may take it.")
+        })
+      },
+      async ({ title, description, reward_usdc, deadline_days, category, tags, agent_only, human_only }) => {
+        if (agent_only && human_only) {
+          return errorResult("agent_only and human_only exclude each other: set at most one of them.");
+        }
+        const overLimit = spendLimitError(reward_usdc, spentUsdc, limits);
+        if (overLimit) return errorResult(overLimit);
+        try {
+          const balance = await agent.usdcBalance();
+          if (balance < BigInt(Math.round(reward_usdc * 1e6))) {
+            return errorResult(
+              `This wallet (${agent.address}) holds ${agent.formatUsdc(balance)} USDC, less than the ${reward_usdc} USDC reward.` + GAS_NOTE
+            );
+          }
+          const result = await agent.createBounty({
+            rewardUsdc: reward_usdc,
+            deadline: (deadline_days ?? 7) * 86400,
+            descriptionText: `# ${title}
+
+${description}`,
+            category,
+            tags: tags ?? [],
+            agentOnly: agent_only ?? false,
+            humanOnly: human_only ?? false
+          });
+          spentUsdc = Math.round((spentUsdc + reward_usdc) * 1e6) / 1e6;
+          const jobId = result.jobId?.toString() ?? null;
+          return json({
+            jobId,
+            txHash: result.hash,
+            url: jobId ? `https://${net.brand.domain}/bounty/${jobId}` : null
+          });
+        } catch (err) {
+          return errorResult(err);
+        }
+      }
+    );
+    server.registerTool(
+      "get_my_posted_bounties",
+      {
+        description: "List the bounties this server's configured wallet has posted, with their state: taken or not, whether work was submitted (hasSubmission), resolved. Open one with get_bounty to read a submission."
+      },
+      async () => {
+        try {
+          const posted = await agent.getPostedBounties();
+          return json(posted.map(summarize));
+        } catch (err) {
+          return errorResult(err);
+        }
+      }
+    );
+    server.registerTool(
+      "approve_bounty",
+      {
+        description: "Approve the work submitted on a bounty this wallet posted: releases the escrowed USDC to the worker (less the 1% fee) and, when the worker is an ERC-8004 agent, writes the score as its on-chain reputation. Final: it cannot be undone. Read the submission with get_bounty first and approve only work that meets the bounty's own acceptance checks. Work that misses them is rejected on the site, where the worker gets 48 hours to challenge.",
+        inputSchema: z.object({
+          jobId: z.string(),
+          score: z.number().int().min(0).max(100).describe("0-100: how well the work met the spec. Recorded as reputation for agent workers.")
+        })
+      },
+      async ({ jobId, score }) => {
+        try {
+          const meta = await agent.getBounty(BigInt(jobId));
+          if (meta.poster.toLowerCase() !== agent.address.toLowerCase()) {
+            return errorResult(
+              `Bounty ${jobId} was posted by ${meta.poster}, not by this wallet (${agent.address}); only its poster can approve it.`
+            );
+          }
+          if (meta.resolved) return errorResult(`Bounty ${jobId} is already resolved.`);
+          if (!meta.submittedResultHash) {
+            return errorResult(`On bounty ${jobId} nothing has been submitted yet, so there is nothing to approve.`);
+          }
+          if (meta.inDispute || meta.rejectedAt > 0n) {
+            return errorResult(
+              `Bounty ${jobId} has a pending rejection or an open dispute; settle that on the site first.`
+            );
+          }
+          const result = await agent.approveBounty(BigInt(jobId), score);
+          return json({ txHash: result.hash, paidTo: meta.assignedProvider });
+        } catch (err) {
+          return errorResult(err);
+        }
+      }
+    );
+    server.registerTool(
+      "cancel_bounty",
+      {
+        description: "Cancel a bounty this wallet posted that nobody has taken yet, refunding the full reward to this wallet. Once a worker has taken it, it can no longer be cancelled.",
+        inputSchema: z.object({ jobId: z.string() })
+      },
+      async ({ jobId }) => {
+        try {
+          const meta = await agent.getBounty(BigInt(jobId));
+          if (meta.poster.toLowerCase() !== agent.address.toLowerCase()) {
+            return errorResult(
+              `Bounty ${jobId} was posted by ${meta.poster}, not by this wallet (${agent.address}); only its poster can cancel it.`
+            );
+          }
+          if (meta.resolved) return errorResult(`Bounty ${jobId} is already resolved.`);
+          if (meta.isTaken) {
+            return errorResult(`Bounty ${jobId} was already taken by ${meta.assignedProvider}, so it cannot be cancelled.`);
+          }
+          const result = await agent.cancelBounty(BigInt(jobId));
+          return json({ txHash: result.hash, refundedUsdc: agent.formatUsdc(meta.reward) });
+        } catch (err) {
+          return errorResult(err);
+        }
+      }
+    );
   }
   return server;
 }
 
 export {
+  readSpendLimits,
   createMcpServer
 };

package/dist/index.js

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
 import {
-  createMcpServer
-} from "./chunk-7ZAUEU5D.js";
+  createMcpServer,
+  readSpendLimits
+} from "./chunk-GY2C2YXQ.js";
 
 // src/index.ts
 import { createRequire } from "module";
@@ -78,9 +79,16 @@ var usingCircleWallet = Boolean(
   process.env["CIRCLE_API_KEY"] && process.env["ENTITY_SECRET"] && process.env["CIRCLE_WALLET_ID"] && process.env["CIRCLE_WALLET_ADDRESS"]
 );
 var hasSigner = Boolean(process.env["AGENT_PRIVATE_KEY"] || usingCircleWallet);
+var limits;
+try {
+  limits = readSpendLimits(process.env);
+} catch (err) {
+  console.error(`${TAG} ${err instanceof Error ? err.message : String(err)}. Server will not start.`);
+  process.exit(1);
+}
 var net = agent.network;
 var BRAND = net.brand.name;
-var server = createMcpServer({ agent, hasSigner, version: pkg.version });
+var server = createMcpServer({ agent, hasSigner, version: pkg.version, limits });
 async function checkRpcChain() {
   const url = process.env["ARC_RPC_URL"]?.trim();
   if (!url) return;

package/dist/tools.d.ts

@@ -1,6 +1,13 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { ArcBountyAgent } from 'arcbounty-agent-sdk';
 
+type SpendLimits = {
+    /** Largest single reward post_bounty accepts, in USDC. */
+    maxRewardUsdc: number;
+    /** Most post_bounty may post in total during one run of this server, in USDC. */
+    maxSpendUsdc: number;
+};
+
 /**
  * Build the MCP server for one already-configured agent.
  *
@@ -13,11 +20,14 @@ import { ArcBountyAgent } from 'arcbounty-agent-sdk';
  * the three read-only tools are registered. A hosted deployment must pass
  * false and mean it, because a signer there would be *our* wallet signing on
  * behalf of whoever called the endpoint.
+ *
+ * `limits` caps what post_bounty may spend - see limits.ts.
  */
-declare function createMcpServer({ agent, hasSigner, version, }: {
+declare function createMcpServer({ agent, hasSigner, version, limits, }: {
     agent: ArcBountyAgent;
     hasSigner: boolean;
     version: string;
+    limits?: SpendLimits;
 }): McpServer;
 
 export { createMcpServer };

package/dist/tools.js

@@ -1,6 +1,6 @@
 import {
   createMcpServer
-} from "./chunk-7ZAUEU5D.js";
+} from "./chunk-GY2C2YXQ.js";
 export {
   createMcpServer
 };

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "arcbounty-mcp",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "mcpName": "io.github.Sofiia7/arcbounty-mcp",
-  "description": "Put an AI agent to work for USDC. MCP server for a live on-chain bounty board where agents and humans take the same jobs: browsing needs no credentials, and with a signing key the agent takes a job, submits the work, and is paid into its own wallet through canonical ERC-8183 escrow, earning ERC-8004 on-chain reputation for every completed job. One package, two networks: Arc (ArcBounty) and Base (BaseBounty).",
+  "description": "Put an AI agent to work for USDC, or let it hire. MCP server for a live on-chain bounty board where agents and humans take the same jobs: browsing needs no credentials; with a signing key the agent takes a job, submits the work and is paid into its own wallet through canonical ERC-8183 escrow, earning ERC-8004 on-chain reputation, or posts bounties of its own, reviews the delivery and pays for it, within operator-set spending caps. One package, two networks: Arc (ArcBounty) and Base (BaseBounty).",
   "type": "module",
   "bin": {
     "arcbounty-mcp": "dist/index.js"
@@ -28,7 +28,8 @@
     "typecheck": "tsc --noEmit",
     "start": "node dist/index.js",
     "pack:mcpb": "npm run build && node sync-manifests.mjs && rm -rf build-mcpb && mkdir -p build-mcpb/server && cp manifest.json build-mcpb/ && cp -r dist build-mcpb/server/ && cp package.json build-mcpb/server/ && npm install --omit=dev --no-package-lock --prefix build-mcpb/server && npx @anthropic-ai/mcpb pack build-mcpb arcbounty-mcp.mcpb && node patch-mcpb.mjs arcbounty-mcp.mcpb manifest.smithery.json arcbounty-mcp-smithery.mcpb",
-    "sync:manifests": "node sync-manifests.mjs"
+    "sync:manifests": "node sync-manifests.mjs",
+    "test": "vitest run"
   },
   "keywords": [
     "mcp",
@@ -44,12 +45,14 @@
     "x402",
     "base",
     "basebounty",
-    "arcbounty"
+    "arcbounty",
+    "hiring",
+    "agent-hiring"
   ],
   "license": "MIT",
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "arcbounty-agent-sdk": "^0.8.0",
+    "arcbounty-agent-sdk": "^0.9.0",
     "viem": "^2.0.0",
     "zod": "^3.23.0"
   },
@@ -57,7 +60,8 @@
     "@types/node": "^25.6.0",
     "tsup": "^8.0.0",
     "tsx": "^4.0.0",
-    "typescript": "^5.0.0"
+    "typescript": "^5.0.0",
+    "vitest": "^4.1.11"
   },
   "exports": {
     ".": "./dist/index.js",