@humanops/mcp-server 0.2.0 → 0.3.0

package/README.md

@@ -0,0 +1,193 @@
+# @humanops/mcp-server
+
+MCP server for AI agents to dispatch real-world tasks to verified human operators.
+
+HumanOps bridges the gap between AI capabilities and physical-world actions. When your agent needs something done in the real world — verifying a business address, filling out a form, solving a CAPTCHA, procuring an API key — it dispatches a task to a verified human operator through this MCP server.
+
+## Installation
+
+```json
+{
+  "mcpServers": {
+    "humanops": {
+      "command": "npx",
+      "args": ["@humanops/mcp-server"],
+      "env": {
+        "HUMANOPS_API_KEY": "your-api-key"
+      }
+    }
+  }
+}
+```
+
+## Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `HUMANOPS_API_KEY` | Yes | Your HumanOps API key |
+| `HUMANOPS_API_URL` | No | API base URL (default: `https://api.humanops.io`) |
+| `HUMANOPS_DEV_ALLOW_LOCALHOST` | No | Set to `true` to allow `HUMANOPS_API_URL` to be `http://localhost:8787` for local development |
+| `HUMANOPS_ALLOW_ANY_API_HOST` | No | Set to `true` to allow non-`*.humanops.io` API hosts (still blocks private/internal hosts) |
+| `HUMANOPS_SANDBOX` | No | Set to `true` to force sandbox mode for non-SANDBOX tier agents (useful for integration testing with VERIFIED/STANDARD accounts) |
+
+## Prerequisites
+
+Before using the MCP server, register your agent via the REST API:
+
+```bash
+curl -X POST https://api.humanops.io/api/v1/agents/register \
+  -H "Content-Type: application/json" \
+  -d '{"name": "my-agent", "email": "agent@example.com"}'
+```
+
+This returns your API key and starts you at **SANDBOX** tier (tasks auto-complete with synthetic proof). To create real tasks:
+
+1. **Verify your email** — click the link in the registration email to upgrade to VERIFIED tier
+2. **Deposit USDC** — send $50+ USDC on Base L2 to upgrade to STANDARD tier
+
+### Agent Tiers
+
+| Tier | Daily Tasks | Max Task Value | Daily Spend | Real Tasks? |
+|------|------------|---------------|-------------|-------------|
+| SANDBOX | 50 | $10 | $10 | No (auto-complete) |
+| VERIFIED | 10 | $100 | $200 | Yes |
+| STANDARD | 100 | $10,000 | $50,000 | Yes |
+
+### Sandbox Mode
+
+SANDBOX tier agents operate in sandbox mode. Every task auto-completes through a simulated lifecycle:
+
+1. Task is created (PENDING) — no funds are escrowed
+2. A simulated operator auto-accepts the task within seconds
+3. Synthetic proof is generated and submitted automatically
+4. A synthetic Guardian verification auto-approves
+5. Task completes — no real money moves, no real human is involved
+
+All API responses for sandbox tasks include `sandbox: true` and a `sandbox_notice` field explaining the simulation. MCP tool outputs prefix sandbox responses with `SANDBOX MODE:` or `SANDBOX TASK:` so your agent clearly understands the results are simulated.
+
+**To exit sandbox mode:** verify your email (upgrades to VERIFIED) and deposit USDC (upgrades to STANDARD).
+
+## Available Tools
+
+### Physical Tasks
+
+| Tool | Description |
+|------|-------------|
+| `search_operators` | Find available operators near a location |
+| `post_task` | Create a physical task (verification, photo, delivery, inspection) |
+
+### Digital Tasks (Tier 1)
+
+| Tool | Description |
+|------|-------------|
+| `dispatch_digital_task` | Create a remote digital task |
+| `list_digital_categories` | List available categories with pricing |
+
+Categories: `CAPTCHA_SOLVING`, `FORM_FILLING`, `BROWSER_INTERACTION`, `CONTENT_REVIEW`, `DATA_VALIDATION`
+
+### Credential Tasks (Tier 2, E2EE)
+
+| Tool | Description |
+|------|-------------|
+| `dispatch_credential_task` | Create an encrypted credential delivery task |
+| `retrieve_credential` | Decrypt and retrieve delivered credentials |
+
+Categories: `ACCOUNT_CREATION`, `API_KEY_PROCUREMENT`, `PHONE_VERIFICATION`, `SUBSCRIPTION_SETUP`
+
+Credential tasks use end-to-end encryption (P-256 ECDH + AES-256-GCM). The server never sees plaintext credentials.
+
+### Task Management
+
+| Tool | Description |
+|------|-------------|
+| `approve_estimate` | Approve an operator's time estimate for an ESTIMATE_PENDING task |
+| `reject_estimate` | Reject an estimate, returning the task to the available pool |
+| `get_task_result` | Get task status, proof, and verification result |
+| `check_verification_status` | Check AI Guardian verification status |
+| `cancel_task` | Cancel a pending/estimate-pending/accepted task (refunds escrowed funds) |
+| `list_tasks` | List your tasks with optional status filter |
+
+### Payments (USDC)
+
+Production safety note: HumanOps uses a shared USDC deposit address on Base L2. To safely
+confirm deposits in production, the API may require you to bind (verify) the wallet you
+deposit from via `POST /api/v1/agents/wallet/challenge` + `PUT /api/v1/agents/wallet`.
+
+| Tool | Description |
+|------|-------------|
+| `get_deposit_address` | Get your USDC deposit address |
+| `fund_account` | Verify a USDC deposit (Base L2) |
+| `get_balance` | Check deposit and escrow balances |
+| `request_payout` | Request operator USDC payout (gas fee deducted from amount) |
+
+## Example Usage
+
+### Dispatch a physical verification task
+
+```
+post_task({
+  title: "Verify business is open",
+  description: "Visit 123 Main St and confirm the restaurant is operating",
+  location: { lat: 40.7128, lng: -74.0060, address: "123 Main St, New York, NY" },
+  reward_usd: 15,
+  deadline: "2026-02-08T18:00:00Z",
+  proof_requirements: ["photo of storefront", "photo of business hours sign"],
+  task_type: "VERIFICATION"
+})
+```
+
+### Dispatch a digital task
+
+```
+dispatch_digital_task({
+  title: "Fill out vendor registration form",
+  description: "Complete the vendor registration at example.com/register",
+  digital_category: "FORM_FILLING",
+  reward_usd: 12,
+  deadline: "2026-02-08T12:00:00Z",
+  proof_requirements: ["screenshot of confirmation page"],
+  digital_instructions: "1. Go to example.com/register\n2. Fill in company details\n3. Submit and screenshot confirmation"
+})
+```
+
+### Dispatch a credential task (E2EE)
+
+```
+dispatch_credential_task({
+  title: "Create API account on DataService",
+  description: "Sign up for a free account and retrieve the API key",
+  digital_category: "API_KEY_PROCUREMENT",
+  reward_usd: 20,
+  deadline: "2026-02-08T12:00:00Z",
+  proof_requirements: ["screenshot of account dashboard"],
+  digital_instructions: "1. Go to dataservice.io/signup\n2. Create account\n3. Navigate to API keys\n4. Generate and submit the key"
+})
+// Returns { task_id, private_key } — save the private_key!
+
+// Later, retrieve the credential:
+retrieve_credential({ task_id: "...", private_key: "..." })
+// Returns { credential: "sk-abc123..." }
+```
+
+## Task Lifecycle
+
+1. **PENDING** — Task created, funds escrowed
+2. **ESTIMATE_PENDING** — Operator submitted a time/cost estimate, awaiting agent approval (24h deadline)
+3. **ACCEPTED** — Operator picked up the task (or estimate approved)
+4. **SUBMITTED** — Operator submitted proof
+5. **VERIFIED** / **REJECTED** — AI Guardian reviewed the proof
+6. **COMPLETED** — Task finished, operator paid
+
+## Security
+
+- All inputs validated with Zod schemas
+- SSRF protection on callback URLs
+- API key sent only to `*.humanops.io` (configurable)
+- Redirects blocked to prevent key exfiltration
+- Credential tasks use client-side E2EE (server never sees plaintext)
+- Single-read credential retrieval (cleared after first read)
+- AI Guardian pre-screens task content at creation time (VERIFIED/STANDARD tiers) — blocks illegal, fraudulent, or abusive tasks
+
+## License
+
+MIT

package/dist/index.js

@@ -123,7 +123,12 @@ async function generateKeyPair() {
     return { publicKey: toBase64(publicRaw), privateKey: toBase64(privateRaw) };
 }
 async function importPublicKey(base64) {
-    return crypto.subtle.importKey("raw", fromBase64(base64), { name: "ECDH", namedCurve: "P-256" }, false, []);
+    const raw = fromBase64(base64);
+    // P-256 uncompressed public key is exactly 65 bytes (0x04 || x || y)
+    if (raw.byteLength !== 65) {
+        throw new Error("Invalid public key length (expected 65 bytes for P-256 uncompressed)");
+    }
+    return crypto.subtle.importKey("raw", raw, { name: "ECDH", namedCurve: "P-256" }, false, []);
 }
 async function importPrivateKey(base64) {
     return crypto.subtle.importKey("pkcs8", fromBase64(base64), { name: "ECDH", namedCurve: "P-256" }, false, ["deriveBits"]);
@@ -145,6 +150,16 @@ async function decryptCredential(encrypted, privateKeyBase64) {
 // ---------------------------------------------------------------------------
 // SSRF protection
 // ---------------------------------------------------------------------------
+// DNS rebinding services that resolve to arbitrary IPs (including private ranges)
+const DNS_REBINDING_BLOCKLIST = [
+    "nip.io", "sslip.io", "xip.io", "nip.test",
+    "localtest.me", "lvh.me", "vcap.me",
+    "lacolhost.com", "yoogle.com",
+    "beweb.com", "servebeer.com", "servecounterstrike.com",
+    "servehalflife.com", "servehttp.com", "serveirc.com",
+    "serveminecraft.net", "servemp3.com", "servepics.com",
+    "servequake.com", "sytes.net",
+];
 function isSSRFSafeUrl(urlStr, requireHttps = false) {
     let parsed;
     try {
@@ -173,6 +188,11 @@ function isSSRFSafeUrl(urlStr, requireHttps = false) {
         return false;
     if (hostname.endsWith(".internal"))
         return false;
+    // Block DNS rebinding services (resolve to attacker-controlled IPs including private ranges)
+    for (const domain of DNS_REBINDING_BLOCKLIST) {
+        if (hostname === domain || hostname.endsWith(`.${domain}`))
+            return false;
+    }
     const ipv4 = parseIpv4(hostname);
     if (ipv4 && isPrivateIpv4(ipv4))
         return false;
@@ -331,6 +351,9 @@ function isPrivateIpv6(groups) {
  * authz/rate-limits/audit logging, it talks to HumanOps via HTTP only.
  */
 const DEFAULT_API_URL = "https://api.humanops.io";
+function isAllowedLocalhost(hostname) {
+    return hostname === "localhost" || hostname === "127.0.0.1" || hostname === "::1";
+}
 function getApiUrl() {
     const raw = process.env.HUMANOPS_API_URL?.trim();
     if (!raw)
@@ -344,11 +367,15 @@ function getApiUrl() {
         throw new Error("HUMANOPS_API_URL must be a valid URL.");
     }
     const allowAnyHost = process.env.HUMANOPS_ALLOW_ANY_API_HOST === "true";
+    const allowLocalhost = process.env.HUMANOPS_DEV_ALLOW_LOCALHOST === "true";
     const hostname = parsed.hostname.trim().toLowerCase().replace(/\.+$/, "");
-    if (!allowAnyHost) {
+    const isHumanopsHost = hostname === "api.humanops.io" || hostname.endsWith(".humanops.io");
+    const isLocalhost = isAllowedLocalhost(hostname);
+    if (!allowAnyHost && !isHumanopsHost) {
         // Prevent accidental exfiltration of HUMANOPS_API_KEY to an unrelated domain.
-        if (hostname !== "api.humanops.io" && !hostname.endsWith(".humanops.io")) {
-            throw new Error("HUMANOPS_API_URL must be api.humanops.io (or *.humanops.io). To override, set HUMANOPS_ALLOW_ANY_API_HOST=true.");
+        // For local development, allow explicit localhost-only override.
+        if (!(allowLocalhost && isLocalhost)) {
+            throw new Error("HUMANOPS_API_URL must be api.humanops.io (or *.humanops.io). To override, set HUMANOPS_ALLOW_ANY_API_HOST=true. For local dev, set HUMANOPS_DEV_ALLOW_LOCALHOST=true and use http://localhost:8787.");
         }
     }
     // Prevent subtle base URL bugs like including paths, querystrings, or fragments.
@@ -359,18 +386,26 @@ function getApiUrl() {
         throw new Error("HUMANOPS_API_URL must not include query params or a fragment.");
     }
     const normalized = parsed.origin;
+    if (allowLocalhost && isLocalhost) {
+        // Explicit opt-in to allow local testing (still blocks redirects, and only applies to localhost).
+        return normalized;
+    }
     if (!isSSRFSafeUrl(normalized, true)) {
         throw new Error("HUMANOPS_API_URL must be a public HTTPS URL (private/internal addresses are blocked).");
     }
     return normalized;
 }
 function getApiKey() {
-    const apiKey = process.env.HUMANOPS_API_KEY;
+    const apiKey = process.env.HUMANOPS_API_KEY?.trim();
     if (!apiKey) {
         throw new Error("HUMANOPS_API_KEY environment variable is required.");
     }
+    if (!/^ho_(live|test)_[a-zA-Z0-9]{32,}$/.test(apiKey)) {
+        console.error("Warning: HUMANOPS_API_KEY does not match expected format (ho_live_... or ho_test_...)");
+    }
     return apiKey;
 }
+const MCP_REQUEST_TIMEOUT = 30_000;
 async function apiRequest(path, init = {}) {
     const baseUrl = getApiUrl();
     const apiKey = getApiKey();
@@ -381,7 +416,7 @@ async function apiRequest(path, init = {}) {
         headers.set("Content-Type", "application/json");
     }
     // Never follow redirects when sending X-API-Key (prevents key exfiltration).
-    const res = await fetch(url, { ...init, headers, redirect: "error" });
+    const res = await fetch(url, { ...init, headers, redirect: "error", signal: AbortSignal.timeout(MCP_REQUEST_TIMEOUT) });
     const contentType = res.headers.get("content-type") ?? "";
     const raw = await res.text();
     const json = contentType.includes("application/json") && raw ? JSON.parse(raw) : null;
@@ -431,7 +466,7 @@ const DispatchDigitalTaskInputSchema = z.object({
     digital_category: DigitalCategoryEnum,
     reward_usd: z.number().min(MIN_TASK_VALUE_USD).max(MAX_TASK_VALUE_USD),
     deadline: z.string().datetime(),
-    proof_requirements: z.array(z.string()).min(1).max(10),
+    proof_requirements: z.array(z.string().min(1).max(500)).min(1).max(10),
     digital_instructions: z.string().max(5000).optional(),
     callback_url: z
         .string()
@@ -449,7 +484,7 @@ const DispatchCredentialTaskInputSchema = z.object({
     digital_category: CredentialCategoryEnum,
     reward_usd: z.number().min(MIN_TASK_VALUE_USD).max(MAX_TASK_VALUE_USD),
     deadline: z.string().datetime(),
-    proof_requirements: z.array(z.string()).min(1).max(10),
+    proof_requirements: z.array(z.string().min(1).max(500)).min(1).max(10),
     digital_instructions: z.string().max(5000).optional(),
     callback_url: z
         .string()
@@ -466,8 +501,8 @@ const RetrieveCredentialInputSchema = z.object({
     private_key: z.string().min(1),
 });
 const SearchOperatorsInputSchema = z.object({
-    lat: z.number(),
-    lng: z.number(),
+    lat: z.number().min(-90).max(90),
+    lng: z.number().min(-180).max(180),
     radius_km: z.number().min(1).max(500).optional(),
     task_type: TaskTypeEnum.optional(),
     min_rating: z.number().min(0).max(5).optional(),
@@ -482,7 +517,7 @@ const PostTaskInputSchema = z.object({
     }),
     reward_usd: z.number().min(MIN_TASK_VALUE_USD).max(MAX_TASK_VALUE_USD),
     deadline: z.string().datetime(),
-    proof_requirements: z.array(z.string()).min(1).max(10),
+    proof_requirements: z.array(z.string().min(1).max(500)).min(1).max(10),
     task_type: TaskTypeEnum,
     callback_url: z
         .string()
@@ -497,12 +532,11 @@ const PostTaskInputSchema = z.object({
 const GetTaskResultInputSchema = z.object({
     task_id: z.string().min(1),
 });
-const USDCChainEnum = z.enum(["base", "polygon", "ethereum", "arbitrum"]);
 const FundAccountInputSchema = z.object({
     amount_usd: z.number().min(MIN_DEPOSIT_USD).max(MAX_DEPOSIT_USD),
     payment_method: z.enum(["usdc", "card", "bank_transfer"]).default("usdc"),
-    tx_hash: z.string().min(1).optional(),
-    chain: USDCChainEnum.optional(),
+    tx_hash: z.string().regex(/^0x[a-fA-F0-9]{64}$/, "Invalid transaction hash (must be 0x-prefixed 64 hex chars)").optional(),
+    chain: z.enum(["base"]).optional(),
     return_url: z
         .string()
         .url()
@@ -514,6 +548,16 @@ const FundAccountInputSchema = z.object({
 const RequestPayoutInputSchema = z.object({
     amount_usd: z.number().min(MIN_PAYOUT_USD),
 });
+const TaskStatusEnum = z.enum([
+    "PENDING", "ESTIMATE_PENDING", "ACCEPTED", "SUBMITTED",
+    "VERIFIED", "REJECTED", "COMPLETED", "CANCELLED", "EXPIRED", "DISPUTED",
+]);
+const ListTasksInputSchema = z.object({
+    status: TaskStatusEnum.optional(),
+    domain: z.enum(["physical", "digital", "all"]).optional(),
+    limit: z.number().int().min(1).max(100).optional(),
+    offset: z.number().int().min(0).optional(),
+});
 const ALL_TASK_TYPES = [
     "VERIFICATION", "PHOTO", "DELIVERY", "INSPECTION",
     "CAPTCHA_SOLVING", "FORM_FILLING", "BROWSER_INTERACTION", "CONTENT_REVIEW", "DATA_VALIDATION",
@@ -521,7 +565,7 @@ const ALL_TASK_TYPES = [
 ];
 const server = new Server({
     name: "humanops",
-    version: "0.2.0",
+    version: "0.3.0",
 }, {
     capabilities: { tools: {} },
 });
@@ -675,7 +719,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
         },
         {
             name: "get_deposit_address",
-            description: "Get your USDC deposit address. Send USDC to this address on a supported chain (Base, Polygon, Ethereum, Arbitrum) to fund your HumanOps account. This is the recommended way to add funds.",
+            description: "Get your USDC deposit address. Send USDC on Base L2 to fund your HumanOps account. This is the recommended way to add funds.",
             inputSchema: {
                 type: "object",
                 properties: {},
@@ -684,7 +728,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
         },
         {
             name: "fund_account",
-            description: "Add funds to your HumanOps account. **Recommended: use USDC deposits** (default). Send USDC to your deposit address (get it via get_deposit_address), then call this with the tx_hash to verify. Fiat methods (card, bank_transfer) are coming soon.",
+            description: "Add funds to your HumanOps account. **Recommended: use USDC deposits** (default). Send USDC on Base L2 to your deposit address (get it via get_deposit_address), then call this with the tx_hash to verify. Fiat methods (card, bank_transfer) are coming soon.",
             inputSchema: {
                 type: "object",
                 properties: {
@@ -698,8 +742,8 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
                     tx_hash: { type: "string", description: "On-chain transaction hash (required for USDC deposits)" },
                     chain: {
                         type: "string",
-                        enum: ["base", "polygon", "ethereum", "arbitrum"],
-                        description: "Blockchain network the USDC was sent on (required for USDC deposits). Base recommended for lowest fees.",
+                        enum: ["base"],
+                        description: "Blockchain network the USDC was sent on (required for USDC deposits). Only Base L2 is supported.",
                     },
                     return_url: { type: "string", description: "Optional return URL after fiat payment (not used for USDC)" },
                 },
@@ -708,7 +752,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
         },
         {
             name: "request_payout",
-            description: "Request a payout of available earnings. Currently only available through the HumanOps operator portal.",
+            description: "Request a payout of available earnings. Operators can withdraw via USDC on Base L2 through the operator portal or API.",
             inputSchema: {
                 type: "object",
                 properties: { amount_usd: { type: "number", description: "Amount to withdraw in USD (min: $10)" } },
@@ -733,13 +777,39 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
                 required: ["task_id"],
             },
         },
+        {
+            name: "approve_estimate",
+            description: "Approve an operator's time estimate for a task. The operator will be notified and can start working. Only works when task status is ESTIMATE_PENDING.",
+            inputSchema: {
+                type: "object",
+                properties: { task_id: { type: "string", description: "The task ID whose estimate to approve" } },
+                required: ["task_id"],
+            },
+        },
+        {
+            name: "reject_estimate",
+            description: "Reject an operator's time estimate for a task. The task returns to the available pool so another operator can claim it. Only works when task status is ESTIMATE_PENDING.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    task_id: { type: "string", description: "The task ID whose estimate to reject" },
+                    reason: { type: "string", description: "Optional reason for rejection (shown to operator)" },
+                },
+                required: ["task_id"],
+            },
+        },
         {
             name: "list_tasks",
             description: "List your tasks with optional status filter. Returns paginated results ordered by creation date.",
             inputSchema: {
                 type: "object",
                 properties: {
-                    status: { type: "string", description: "Filter by status (e.g., PENDING, ACCEPTED, COMPLETED)" },
+                    status: {
+                        type: "string",
+                        enum: ["PENDING", "ESTIMATE_PENDING", "ACCEPTED", "SUBMITTED", "VERIFIED", "REJECTED", "COMPLETED", "CANCELLED", "EXPIRED", "DISPUTED"],
+                        description: "Filter by task status",
+                    },
+                    domain: { type: "string", enum: ["physical", "digital", "all"], description: "Filter by task domain (default: all)" },
                     limit: { type: "number", description: "Max results (default: 20, max: 100)" },
                     offset: { type: "number", description: "Pagination offset (default: 0)" },
                 },
@@ -792,6 +862,15 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     body: JSON.stringify(body),
                     headers,
                 });
+                // Surface sandbox_notice prominently so the agent understands what happened
+                const resultObj = result;
+                if (resultObj.sandbox) {
+                    return {
+                        content: [
+                            { type: "text", text: `SANDBOX MODE: ${resultObj.sandbox_notice ?? "This task will auto-complete with simulated proof. No real operator is involved."}\n\n${JSON.stringify(result, null, 2)}` },
+                        ],
+                    };
+                }
                 return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
             }
             case "get_task_result": {
@@ -805,6 +884,15 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 const result = await apiRequest(`/api/v1/tasks/${encodeURIComponent(parsed.data.task_id)}`, {
                     method: "GET",
                 });
+                // Surface sandbox notice prominently
+                const taskObj = result;
+                if (taskObj.sandbox) {
+                    return {
+                        content: [
+                            { type: "text", text: `SANDBOX TASK: ${taskObj.sandbox_notice ?? "This task was simulated — operator, proof, and verification are all synthetic."}\n\n${JSON.stringify(result, null, 2)}` },
+                        ],
+                    };
+                }
                 return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
             }
             case "check_verification_status": {
@@ -824,6 +912,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     guardian_result: task.guardian_result,
                     verified_at: task.verified_at ?? null,
                     completed_at: task.completed_at ?? null,
+                    ...(task.sandbox && { sandbox: true, sandbox_notice: "Verification result is synthetic — this was a simulated sandbox task." }),
                 };
                 return { content: [{ type: "text", text: JSON.stringify(focused, null, 2) }] };
             }
@@ -837,7 +926,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                             type: "text",
                             text: JSON.stringify({
                                 ...result,
-                                _instructions: "Send USDC to this address on the specified chain. After sending, use fund_account with the tx_hash and chain to verify your deposit.",
+                                _instructions: "Send USDC to this address on the specified chain. Production safety: you may need to bind the wallet you deposit from (POST /api/v1/agents/wallet/challenge + PUT /api/v1/agents/wallet) before verifying deposits. After sending, use fund_account with tx_hash + chain to verify.",
                             }, null, 2),
                         },
                     ],
@@ -851,8 +940,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                         isError: true,
                     };
                 }
-                const { amount_usd, payment_method, tx_hash, chain, return_url } = parsed.data;
-                const method = payment_method ?? "usdc";
+                const { amount_usd, payment_method: method, tx_hash, chain, return_url } = parsed.data;
                 // Fiat methods are coming soon
                 if (method === "card" || method === "bank_transfer") {
                     return {
@@ -882,7 +970,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                                 text: JSON.stringify({
                                     status: "awaiting_deposit",
                                     ...addressResult,
-                                    message: "No tx_hash provided. Send USDC to the address above, then call fund_account again with the tx_hash and chain to verify your deposit.",
+                                    message: "No tx_hash provided. Send USDC to the address above. If the API says your deposit wallet is not verified, bind it first via POST /api/v1/agents/wallet/challenge + PUT /api/v1/agents/wallet. Then call fund_account again with tx_hash + chain to verify your deposit.",
                                 }, null, 2),
                             },
                         ],
@@ -891,7 +979,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 const result = await apiRequest("/api/v1/agents/deposit/usdc", {
                     method: "POST",
                     body: JSON.stringify({
-                        amount_usd,
+                        amount_usdc: amount_usd,
                         tx_hash,
                         chain: chain ?? "base",
                     }),
@@ -911,9 +999,9 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                         {
                             type: "text",
                             text: JSON.stringify({
-                                status: "unavailable",
+                                status: "operator_only",
                                 amount_requested: parsed.data.amount_usd,
-                                message: "Payouts are currently only available through the HumanOps operator portal (https://humanops.io). MCP-based payouts will be available in a future release.",
+                                message: "Payouts are processed via the operator portal. Operators can withdraw USDC on Base L2 by setting a wallet address and requesting a payout through the operator API (PUT /operator/wallet + POST /operator/payout).",
                             }, null, 2),
                         },
                     ],
@@ -921,6 +1009,19 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             }
             case "get_balance": {
                 const data = await apiRequest("/api/v1/agents/balance", { method: "GET" });
+                const balanceObj = data;
+                const depositBalance = Number(balanceObj.deposit_balance ?? 0);
+                const hints = [];
+                if (depositBalance === 0) {
+                    hints.push("Your balance is $0. To create real tasks, deposit USDC via get_deposit_address + fund_account.");
+                }
+                if (hints.length > 0) {
+                    return {
+                        content: [
+                            { type: "text", text: `${hints.join(" ")}\n\n${JSON.stringify(data, null, 2)}` },
+                        ],
+                    };
+                }
                 return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
             }
             case "cancel_task": {
@@ -936,16 +1037,55 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 });
                 return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
             }
+            case "approve_estimate": {
+                const parsed = GetTaskResultInputSchema.safeParse(args);
+                if (!parsed.success) {
+                    return {
+                        content: [{ type: "text", text: `Error: invalid input: ${parsed.error.message}` }],
+                        isError: true,
+                    };
+                }
+                const result = await apiRequest(`/api/v1/tasks/${encodeURIComponent(parsed.data.task_id)}/estimate/approve`, {
+                    method: "POST",
+                });
+                return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+            }
+            case "reject_estimate": {
+                const rejectSchema = z.object({
+                    task_id: z.string().min(1),
+                    reason: z.string().max(1000).optional(),
+                });
+                const parsed = rejectSchema.safeParse(args);
+                if (!parsed.success) {
+                    return {
+                        content: [{ type: "text", text: `Error: invalid input: ${parsed.error.message}` }],
+                        isError: true,
+                    };
+                }
+                const body = parsed.data.reason ? JSON.stringify({ reason: parsed.data.reason }) : undefined;
+                const result = await apiRequest(`/api/v1/tasks/${encodeURIComponent(parsed.data.task_id)}/estimate/reject`, {
+                    method: "POST",
+                    ...(body ? { body } : {}),
+                });
+                return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+            }
             case "list_tasks": {
-                const params = new URLSearchParams();
-                if (args && typeof args === "object") {
-                    if (args.status)
-                        params.set("status", String(args.status));
-                    if (args.limit)
-                        params.set("limit", String(args.limit));
-                    if (args.offset)
-                        params.set("offset", String(args.offset));
+                const parsed = ListTasksInputSchema.safeParse(args ?? {});
+                if (!parsed.success) {
+                    return {
+                        content: [{ type: "text", text: `Error: invalid input: ${parsed.error.message}` }],
+                        isError: true,
+                    };
                 }
+                const params = new URLSearchParams();
+                if (parsed.data.status)
+                    params.set("status", parsed.data.status);
+                if (parsed.data.domain)
+                    params.set("domain", parsed.data.domain);
+                if (parsed.data.limit !== undefined)
+                    params.set("limit", String(parsed.data.limit));
+                if (parsed.data.offset !== undefined)
+                    params.set("offset", String(parsed.data.offset));
                 const query = params.toString();
                 const data = await apiRequest(`/api/v1/tasks${query ? `?${query}` : ""}`, { method: "GET" });
                 return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
@@ -990,6 +1130,14 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     body: JSON.stringify(payload),
                     headers,
                 });
+                const digitalResultObj = result;
+                if (digitalResultObj.sandbox) {
+                    return {
+                        content: [
+                            { type: "text", text: `SANDBOX MODE: ${digitalResultObj.sandbox_notice ?? "This task will auto-complete with simulated proof."}\n\n${JSON.stringify(result, null, 2)}` },
+                        ],
+                    };
+                }
                 return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
             }
             case "dispatch_credential_task": {
@@ -1040,6 +1188,14 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     private_key: keyPair.privateKey,
                     _notice: "IMPORTANT: Save the private_key securely. You need it to decrypt the credential using retrieve_credential.",
                 };
+                const credResultObj = result;
+                if (credResultObj.sandbox) {
+                    return {
+                        content: [
+                            { type: "text", text: `SANDBOX MODE: ${credResultObj.sandbox_notice ?? "This credential task will auto-complete with simulated data. No real credentials will be delivered."}\n\n${JSON.stringify(response, null, 2)}` },
+                        ],
+                    };
+                }
                 return { content: [{ type: "text", text: JSON.stringify(response, null, 2) }] };
             }
             case "retrieve_credential": {
@@ -1079,7 +1235,24 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     }
                     throw retrieveErr;
                 }
-                const plaintext = await decryptCredential(retrieveResult.encrypted_credential, private_key);
+                let plaintext;
+                try {
+                    plaintext = await decryptCredential(retrieveResult.encrypted_credential, private_key);
+                }
+                catch (decryptErr) {
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: JSON.stringify({
+                                    task_id,
+                                    error: "Decryption failed. This usually means the private_key does not match the keypair used when creating the task. Ensure you are using the exact private_key returned by dispatch_credential_task.",
+                                }, null, 2),
+                            },
+                        ],
+                        isError: true,
+                    };
+                }
                 return {
                     content: [
                         {
@@ -1114,13 +1287,18 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         }
     }
     catch (err) {
-        const errorMessage = err.message || "Unknown error";
-        const isNetworkError = errorMessage.includes("fetch failed") || errorMessage.includes("ECONNREFUSED");
+        const rawMessage = err.message || "Unknown error";
+        const isNetworkError = rawMessage.includes("fetch failed") || rawMessage.includes("ECONNREFUSED");
+        // Sanitize: strip stack traces, internal paths, and limit length
+        let safeMessage = rawMessage
+            .replace(/\bat\s+.+\(.+\)/g, "")
+            .replace(/\/[^\s:]+\.(ts|js):\d+/g, "[internal]")
+            .slice(0, 500);
         const hint = isNetworkError
             ? " (Network error — check your HUMANOPS_API_URL and HUMANOPS_API_KEY configuration.)"
             : "";
         return {
-            content: [{ type: "text", text: `Error: ${errorMessage}${hint}` }],
+            content: [{ type: "text", text: `Error: ${safeMessage}${hint}` }],
             isError: true,
         };
     }
@@ -1128,12 +1306,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 async function main() {
     const transport = new StdioServerTransport();
     await server.connect(transport);
-    if (process.env.NODE_ENV !== "production") {
-        console.error(`HumanOps MCP Server running on stdio (api=${getApiUrl()})`);
-    }
-    else {
-        console.error("HumanOps MCP Server running on stdio");
-    }
+    console.error("HumanOps MCP Server running on stdio");
 }
 main().catch((err) => {
     console.error("Failed to start MCP server:", err);

package/package.json

@@ -1,21 +1,25 @@
 {
   "name": "@humanops/mcp-server",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "mcpName": "io.github.thepianistdirector/humanops",
   "description": "MCP server for AI agents to dispatch real-world tasks to verified human operators via HumanOps",
   "type": "module",
   "main": "./dist/index.js",
   "bin": {
-    "humanops-mcp": "./dist/index.js"
+    "humanops-mcp": "dist/index.js"
   },
-  "files": ["dist/*.js", "dist/*.d.ts"],
+  "files": ["dist/*.js", "dist/*.d.ts", "README.md"],
   "scripts": {
     "start": "node dist/index.js",
     "dev": "tsx watch src/index.ts",
     "build": "tsc",
+    "smoke:local": "node scripts/smoke-local.mjs",
     "prepublishOnly": "npm run build",
     "lint": "tsc --noEmit"
   },
+  "engines": {
+    "node": ">=18"
+  },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",
     "zod": "^3.24.0"
@@ -26,8 +30,13 @@
   },
   "license": "MIT",
   "keywords": ["humanops", "mcp", "ai", "agents", "tasks", "model-context-protocol"],
+  "author": "HumanOps <hello@humanops.io>",
+  "homepage": "https://humanops.io",
+  "bugs": {
+    "url": "https://github.com/thepianistdirector/humanops/issues"
+  },
   "repository": {
     "type": "git",
-    "url": "https://github.com/ThePianistDirector/real-auto-code"
+    "url": "https://github.com/thepianistdirector/humanops"
   }
 }