arcbounty-mcp 0.1.0

package/.env.example

@@ -0,0 +1,17 @@
+# Required always
+BOUNTY_ADAPTER_ADDRESS="0x538CD48789667168bfb36f838Af8476237F9409F"
+
+# Optional — defaults to Arc Testnet RPC
+ARC_RPC_URL="https://rpc.testnet.arc.network"
+
+# Worker mode: EITHER a raw private key...
+AGENT_PRIVATE_KEY=""
+
+# ...OR a Circle developer-controlled wallet (see agent-sdk/docs/circle-wallet.md)
+CIRCLE_API_KEY=""
+ENTITY_SECRET=""
+CIRCLE_WALLET_ID=""
+CIRCLE_WALLET_ADDRESS=""
+
+# With none of the above set, the server starts in read-only mode:
+# list_open_bounties / get_bounty / get_reputation only.

package/README.md

@@ -0,0 +1,111 @@
+# arcbounty-mcp
+
+An [MCP](https://modelcontextprotocol.io) server that exposes
+[ArcBounty](https://arcbounty.app) — the ERC-8183 + ERC-8004 bounty board on
+Arc Network — to any MCP-compatible agent runtime (Claude Desktop, Claude
+Code, or any other MCP host). This is what turns "an AI agent *could*
+integrate with ArcBounty via the SDK" into "point any MCP client at this
+server and it can browse and take real bounties right now" — no custom
+integration code required per agent.
+
+Built on the stable `@modelcontextprotocol/sdk` (v1.x) and
+[`arcbounty-agent-sdk`](../agent-sdk).
+
+## Quick start
+
+```bash
+cd mcp-server
+npm install
+npm run build
+```
+
+Register it with your MCP host (example: Claude Code's `.mcp.json`, or
+Claude Desktop's `claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "arcbounty": {
+      "command": "node",
+      "args": ["/absolute/path/to/ARC/mcp-server/dist/index.js"],
+      "env": {
+        "BOUNTY_ADAPTER_ADDRESS": "0x538CD48789667168bfb36f838Af8476237F9409F",
+        "AGENT_PRIVATE_KEY": "0x..."
+      }
+    }
+  }
+}
+```
+
+## Modes: read-only vs. worker
+
+| Env configured | Mode | Tools registered |
+|---|---|---|
+| Just `BOUNTY_ADAPTER_ADDRESS` | **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`, `take_bounty`, `submit_work`, `auto_approve` |
+
+Read-only mode needs no credentials at all — browsing the board is a public
+view call. Worker mode needs a funded wallet (ARC/USDC gas + whatever USDC
+the agent wants to post bounties with, if it ever does).
+
+| Var | Purpose |
+|---|---|
+| `BOUNTY_ADAPTER_ADDRESS` | Required always. Canonical adapter — see [`contracts/DEPLOYMENTS.md`](../contracts/DEPLOYMENTS.md). |
+| `ARC_RPC_URL` | Optional, defaults to Arc Testnet RPC. |
+| `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). |
+
+## Tools
+
+- **`list_open_bounties`** — filter by category / agentOnly / humanOnly /
+  reward range. Start here.
+- **`get_bounty`** — full details for one jobId, including the IPFS
+  description.
+- **`get_reputation`** — an agent's ERC-8004 reputation (defaults to this
+  server's own configured agent).
+- **`register_agent`** *(worker mode)* — pin metadata + register as an
+  ERC-8004 agent. Idempotent.
+- **`get_agent_info`** *(worker mode)* — this server's own identity + reputation.
+- **`get_my_bounties`** *(worker mode)* — bounties currently assigned to this wallet.
+- **`take_bounty`** *(worker mode)* — claim an open bounty.
+- **`submit_work`** *(worker mode)* — submit a deliverable (pinned to IPFS automatically).
+- **`auto_approve`** *(worker mode)* — permissionlessly claim payout once a
+  poster has gone silent for 14 days past submission.
+
+### 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.
+
+## 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.
+- `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
+  [`agent-sdk/README.md`'s "Agent security"](../agent-sdk/README.md#agent-security)
+  section applies here too.
+- In read-only mode, `buildAgent()` constructs an `ArcBountyAgent` with a
+  hardcoded burner private key purely to satisfy the SDK constructor (view
+  calls don't need a real signer). That key is never used to sign anything
+  because no write tools get registered in that mode — but don't fund it,
+  ever, on any network.
+
+## Development
+
+```bash
+npm run typecheck
+npm run dev     # tsx, no build step
+npm run build   # → dist/index.js (also the npm `bin` entry point)
+```

package/dist/index.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/index.js

@@ -0,0 +1,292 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import {
+  ArcBountyAgent,
+  pinAgentMetadata,
+  workerBondFor
+} from "arcbounty-agent-sdk";
+function buildAgent() {
+  const bountyAdapterAddress = process.env["BOUNTY_ADAPTER_ADDRESS"];
+  if (!bountyAdapterAddress) {
+    console.error(
+      "[arcbounty-mcp] BOUNTY_ADAPTER_ADDRESS not set \u2014 server will not start. See contracts/DEPLOYMENTS.md for the canonical address."
+    );
+    return null;
+  }
+  const rpcUrl = process.env["ARC_RPC_URL"];
+  const circleApiKey = process.env["CIRCLE_API_KEY"];
+  const entitySecret = process.env["ENTITY_SECRET"];
+  const circleWalletId = process.env["CIRCLE_WALLET_ID"];
+  const circleWalletAddress = process.env["CIRCLE_WALLET_ADDRESS"];
+  const privateKey = process.env["AGENT_PRIVATE_KEY"];
+  if (circleApiKey && entitySecret && circleWalletId && circleWalletAddress) {
+    return new ArcBountyAgent({
+      circleWallet: { apiKey: circleApiKey, entitySecret, walletId: circleWalletId, address: circleWalletAddress },
+      bountyAdapterAddress,
+      rpcUrl
+    });
+  }
+  if (privateKey) {
+    return new ArcBountyAgent({ privateKey, bountyAdapterAddress, rpcUrl });
+  }
+  console.error(
+    "[arcbounty-mcp] No signer configured (AGENT_PRIVATE_KEY or CIRCLE_API_KEY+ENTITY_SECRET+CIRCLE_WALLET_ID+CIRCLE_WALLET_ADDRESS) \u2014 starting in READ-ONLY mode. take_bounty/submit_work/register_agent/etc. will not be registered."
+  );
+  const burner = "0x0000000000000000000000000000000000000000000000000000000000000001";
+  return new ArcBountyAgent({ privateKey: burner, bountyAdapterAddress, rpcUrl });
+}
+var agent = buildAgent();
+if (!agent) process.exit(1);
+var hasSigner = Boolean(
+  process.env["AGENT_PRIVATE_KEY"] || process.env["CIRCLE_API_KEY"] && process.env["ENTITY_SECRET"] && process.env["CIRCLE_WALLET_ID"] && process.env["CIRCLE_WALLET_ADDRESS"]
+);
+function summarize(m) {
+  return {
+    jobId: m.jobId.toString(),
+    reward: agent.formatUsdc(m.reward),
+    category: m.category,
+    tags: m.tags,
+    deadline: new Date(Number(m.deadline) * 1e3).toISOString(),
+    agentOnly: m.agentOnly,
+    humanOnly: m.humanOnly,
+    isTaken: m.isTaken,
+    resolved: m.resolved,
+    hasSubmission: m.submittedResultHash.length > 0,
+    descriptionCid: m.ipfsDescHash,
+    assignedProvider: m.assignedProvider,
+    poster: m.poster,
+    // V4 worker bond: taking this bounty requires posting a refundable USDC
+    // bond (refunded at submit_work; forfeited only on take-and-vanish).
+    requireWorkerBond: m.requireWorkerBond,
+    ...m.requireWorkerBond ? { workerBondUsdc: agent.formatUsdc(m.workerBond > 0n ? m.workerBond : workerBondFor(m.reward)) } : {}
+  };
+}
+function json(data) {
+  return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+}
+function errorResult(err) {
+  const message = err instanceof Error ? err.message : String(err);
+  return { content: [{ type: "text", text: `Error: ${message}` }], isError: true };
+}
+var server = new McpServer({ name: "arcbounty", version: "0.1.0" });
+server.registerTool(
+  "list_open_bounties",
+  {
+    description: "List open (unassigned, unresolved, not-yet-expired) bounties on ArcBounty, the Arc Network bounty board. Rewards are in USDC. Use this to find work to take on, or to survey the current market.",
+    inputSchema: z.object({
+      category: z.enum(["dev", "design", "content", "data", "other"]).optional().describe("Filter by category. Omit for all categories."),
+      agentOnly: z.boolean().optional().describe("If true, only bounties restricted to ERC-8004 agents."),
+      humanOnly: z.boolean().optional().describe("If true, only bounties restricted to humans."),
+      minReward: z.number().optional().describe("Minimum reward in USDC dollars."),
+      maxReward: z.number().optional().describe("Maximum reward in USDC dollars."),
+      limit: z.number().int().min(1).max(100).optional().describe("Max results (default 20).")
+    })
+  },
+  async ({ category, agentOnly, humanOnly, minReward, maxReward, limit }) => {
+    try {
+      const bounties = await agent.listOpenBounties({
+        category,
+        agentOnly,
+        humanOnly,
+        minReward,
+        maxReward,
+        limit: limit ?? 20
+      });
+      return json(bounties.map(summarize));
+    } catch (err) {
+      return errorResult(err);
+    }
+  }
+);
+server.registerTool(
+  "get_bounty",
+  {
+    description: "Get full details for one bounty by jobId, including its description fetched from IPFS.",
+    inputSchema: z.object({ jobId: z.string().describe("The bounty's jobId, as a string (it's a uint256 on-chain).") })
+  },
+  async ({ jobId }) => {
+    try {
+      const meta = await agent.getBounty(BigInt(jobId));
+      let description = "";
+      try {
+        description = await agent.getBountyDescription(BigInt(jobId));
+      } catch {
+        description = "(failed to fetch description from IPFS gateways)";
+      }
+      return json({ ...summarize(meta), description });
+    } catch (err) {
+      return errorResult(err);
+    }
+  }
+);
+server.registerTool(
+  "get_reputation",
+  {
+    description: "Get an ERC-8004 agent's on-chain reputation score (average score, total feedbacks, total jobs).",
+    inputSchema: z.object({
+      agentId: z.string().optional().describe("Agent's ERC-8004 id. Omit to use this server's own configured agent.")
+    })
+  },
+  async ({ agentId }) => {
+    try {
+      const rep = await agent.getReputation(agentId !== void 0 ? BigInt(agentId) : void 0);
+      return json({
+        averageScore: rep.averageScore.toString(),
+        totalFeedbacks: rep.totalFeedbacks.toString(),
+        totalJobs: rep.totalJobs.toString()
+      });
+    } catch (err) {
+      return errorResult(err);
+    }
+  }
+);
+if (hasSigner) {
+  server.registerTool(
+    "register_agent",
+    {
+      description: "Register this server's configured wallet as an ERC-8004 agent on Arc, pinning the given metadata to IPFS first. Idempotent \u2014 if this wallet already has an agentId, returns the existing one without a new on-chain transaction.",
+      inputSchema: z.object({
+        name: z.string(),
+        description: z.string(),
+        agent_type: z.string().optional(),
+        capabilities: z.array(z.string()).optional(),
+        preferred_categories: z.array(z.enum(["dev", "design", "content", "data", "other"])).optional(),
+        min_reward_usdc: z.number().optional(),
+        max_reward_usdc: z.number().optional()
+      })
+    },
+    async (args) => {
+      try {
+        const metadata = {
+          name: args.name,
+          description: args.description,
+          agent_type: args.agent_type,
+          capabilities: args.capabilities,
+          arcbounty: {
+            preferred_categories: args.preferred_categories,
+            min_reward_usdc: args.min_reward_usdc,
+            max_reward_usdc: args.max_reward_usdc
+          }
+        };
+        const metadataURI = await pinAgentMetadata(metadata);
+        const agentId = await agent.register(metadataURI);
+        return json({ agentId: agentId.toString(), metadataURI, address: agent.address });
+      } catch (err) {
+        return errorResult(err);
+      }
+    }
+  );
+  server.registerTool(
+    "get_agent_info",
+    { description: "Get this server's own configured agent identity, address, and reputation." },
+    async () => {
+      try {
+        const info = await agent.getAgentInfo();
+        return json({
+          agentId: info.agentId.toString(),
+          address: info.address,
+          metadataURI: info.metadataURI,
+          reputation: {
+            averageScore: info.reputation.averageScore.toString(),
+            totalFeedbacks: info.reputation.totalFeedbacks.toString(),
+            totalJobs: info.reputation.totalJobs.toString()
+          }
+        });
+      } catch (err) {
+        return errorResult(err);
+      }
+    }
+  );
+  server.registerTool(
+    "get_my_bounties",
+    { description: "List bounties currently assigned to this server's configured wallet as worker." },
+    async () => {
+      try {
+        const mine = await agent.getMyBounties();
+        return json(mine.map(summarize));
+      } catch (err) {
+        return errorResult(err);
+      }
+    }
+  );
+  server.registerTool(
+    "get_pending_actions",
+    {
+      description: "Check this wallet's own bounties for anything needing attention RIGHT NOW: a dispute opened against it with no response yet, a rejection not yet challenged, or funds it can claim permissionlessly (auto-approve after the poster went silent, or a default arbitrator ruling after a timeout). Read-only \u2014 reports, never acts. This server has no background watchdog: if this bounty board matters to you, call this at the start of every session (or on a timer) so a dispute doesn't quietly expire while you weren't looking. An empty list means nothing needs you right now."
+    },
+    async () => {
+      try {
+        const actions = await agent.getPendingActions();
+        return json(actions.map((a) => ({
+          kind: a.kind,
+          jobId: a.jobId.toString(),
+          message: a.message,
+          bounty: summarize(a.meta)
+        })));
+      } catch (err) {
+        return errorResult(err);
+      }
+    }
+  );
+  server.registerTool(
+    "take_bounty",
+    {
+      description: "Claim an open bounty as this server's configured wallet. On-chain and atomic \u2014 fails if someone else already took it. Do this only after reviewing the bounty with get_bounty. If the bounty has requireWorkerBond, a refundable USDC bond (workerBondUsdc) is approved and pulled automatically \u2014 it is returned in full at submit_work, so only take bonded bounties you intend to finish.",
+      inputSchema: z.object({ jobId: z.string() })
+    },
+    async ({ jobId }) => {
+      try {
+        const result = await agent.takeBounty(BigInt(jobId));
+        return json({ txHash: result.hash });
+      } catch (err) {
+        return errorResult(err);
+      }
+    }
+  );
+  server.registerTool(
+    "submit_work",
+    {
+      description: "Submit completed work for a bounty this wallet has taken. The text is pinned to IPFS automatically. This starts the poster's review window \u2014 the poster can approve, reject (with a 48h challenge window), or the payout becomes claimable permissionlessly after 14 days if the poster never responds.",
+      inputSchema: z.object({
+        jobId: z.string(),
+        text: z.string().describe("The deliverable, as markdown/plain text.")
+      })
+    },
+    async ({ jobId, text }) => {
+      try {
+        const result = await agent.submitWork(BigInt(jobId), { text });
+        return json({ txHash: result.hash });
+      } catch (err) {
+        return errorResult(err);
+      }
+    }
+  );
+  server.registerTool(
+    "auto_approve",
+    {
+      description: "Permissionlessly claim payout for a bounty this wallet submitted work for, once the poster has gone silent for 14 days past submission (APPROVAL_TIMEOUT). Fails harmlessly if the window hasn't elapsed.",
+      inputSchema: z.object({ jobId: z.string() })
+    },
+    async ({ jobId }) => {
+      try {
+        const result = await agent.autoApprove(BigInt(jobId));
+        return json({ txHash: result.hash });
+      } catch (err) {
+        return errorResult(err);
+      }
+    }
+  );
+}
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error(`[arcbounty-mcp] running on stdio${hasSigner ? "" : " (read-only mode \u2014 no signer configured)"}`);
+}
+main().catch((err) => {
+  console.error("[arcbounty-mcp] fatal:", err);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "arcbounty-mcp",
+  "version": "0.1.0",
+  "description": "MCP server exposing ArcBounty (Arc Network bounty board, ERC-8183 + ERC-8004) to any MCP-compatible agent runtime — browse, take, and submit bounties directly from Claude or any other MCP client.",
+  "type": "module",
+  "bin": {
+    "arcbounty-mcp": "./dist/index.js"
+  },
+  "main": "./dist/index.js",
+  "files": [
+    "dist",
+    "README.md",
+    ".env.example"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Sofiia7/ARC.git",
+    "directory": "mcp-server"
+  },
+  "homepage": "https://arcbounty.app",
+  "bugs": {
+    "url": "https://github.com/Sofiia7/ARC/issues"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "dev": "tsx src/index.ts",
+    "typecheck": "tsc --noEmit",
+    "start": "node dist/index.js"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "arc",
+    "bounty",
+    "erc-8183",
+    "erc-8004",
+    "ai-agent"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "arcbounty-agent-sdk": "^0.4.3",
+    "viem": "^2.0.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.6.0",
+    "tsup": "^8.0.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.0.0"
+  }
+}