@humanops/mcp-server 0.3.1 → 0.3.2

package/README.md

@@ -24,7 +24,7 @@ HumanOps bridges the gap between AI capabilities and physical-world actions. Whe
 
 | Variable | Required | Description |
 |----------|----------|-------------|
-| `HUMANOPS_API_KEY` | Yes | Your HumanOps API key |
+| `HUMANOPS_API_KEY` | Yes* | Your HumanOps API key. Not required to run the unauthenticated `register_agent` tool, but required for all other tools. |
 | `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) |
@@ -32,7 +32,15 @@ HumanOps bridges the gap between AI capabilities and physical-world actions. Whe
 
 ## Prerequisites
 
-Before using the MCP server, register your agent via the REST API:
+Register your agent (get an API key) using one of the following:
+
+### Option A: Register via MCP (Recommended)
+
+Call the `register_agent` tool first (no `HUMANOPS_API_KEY` required). It returns an `api_key`.
+
+Then set `HUMANOPS_API_KEY` to that key (restart the MCP server) to use authenticated tools.
+
+### Option B: Register via REST API
 
 ```bash
 curl -X POST https://api.humanops.io/api/v1/agents/register \

package/dist/index.js

@@ -395,23 +395,30 @@ function getApiUrl() {
     }
     return normalized;
 }
-function getApiKey() {
+function getApiKeyOptional() {
     const apiKey = process.env.HUMANOPS_API_KEY?.trim();
-    if (!apiKey) {
-        throw new Error("HUMANOPS_API_KEY environment variable is required.");
-    }
+    if (!apiKey)
+        return null;
     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;
 }
+function getApiKeyRequired() {
+    const apiKey = getApiKeyOptional();
+    if (!apiKey) {
+        throw new Error("HUMANOPS_API_KEY environment variable is required for this tool.");
+    }
+    return apiKey;
+}
 const MCP_REQUEST_TIMEOUT = 30_000;
-async function apiRequest(path, init = {}) {
+async function apiRequest(path, init = {}, opts) {
     const baseUrl = getApiUrl();
-    const apiKey = getApiKey();
     const url = `${baseUrl}${path}`;
     const headers = new Headers(init.headers);
-    headers.set("X-API-Key", apiKey);
+    if (opts?.auth !== false) {
+        headers.set("X-API-Key", getApiKeyRequired());
+    }
     if (!headers.has("Content-Type") && init.body && typeof init.body === "string") {
         headers.set("Content-Type", "application/json");
     }
@@ -545,6 +552,20 @@ const FundAccountInputSchema = z.object({
     })
         .optional(),
 });
+const GetWalletChallengeInputSchema = z.object({
+    chain: z.enum(["base"]).optional(),
+});
+const BindWalletInputSchema = z.object({
+    wallet_address: z.string().regex(/^0x[a-fA-F0-9]{40}$/, "Invalid wallet_address (must be a 0x-prefixed address)"),
+    nonce: z.string().min(1).max(200),
+    signature: z.string().min(10).max(5000),
+    chain: z.enum(["base"]).optional(),
+});
+const RegisterAgentInputSchema = z.object({
+    name: z.string().min(1).max(200),
+    email: z.string().email(),
+    company: z.string().min(1).max(200).optional(),
+});
 const RequestPayoutInputSchema = z.object({
     amount_usd: z.number().min(MIN_PAYOUT_USD),
 });
@@ -717,6 +738,28 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
                 required: ["task_id"],
             },
         },
+        {
+            name: "register_agent",
+            description: "Register a new HumanOps agent account. Returns an API key for authentication. You start in SANDBOX tier (tasks auto-complete with simulated operators). Verify your email to upgrade to VERIFIED tier.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    name: { type: "string", description: "Agent name" },
+                    email: { type: "string", description: "Agent email (must be unique)" },
+                    company: { type: "string", description: "Optional company name" },
+                },
+                required: ["name", "email"],
+            },
+        },
+        {
+            name: "get_agent_status",
+            description: "Check your current agent status including tier, email verification, wallet binding, and balances. Also returns clear upgrade steps.",
+            inputSchema: {
+                type: "object",
+                properties: {},
+                required: [],
+            },
+        },
         {
             name: "get_deposit_address",
             description: "Get your USDC deposit address. Send USDC on Base L2 to fund your HumanOps account. This is the recommended way to add funds.",
@@ -726,6 +769,31 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
                 required: [],
             },
         },
+        {
+            name: "get_wallet_challenge",
+            description: "Get a challenge message to sign with your EVM wallet. Sign this message to prove wallet ownership before depositing USDC. In production, wallet binding is required before deposits can be confirmed.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    chain: { type: "string", enum: ["base"], description: "Blockchain network (default: base)" },
+                },
+                required: [],
+            },
+        },
+        {
+            name: "bind_wallet",
+            description: "Bind your EVM wallet after signing the challenge message. This verifies wallet ownership. Required once before confirming USDC deposits in production.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    wallet_address: { type: "string", description: "0x-prefixed EVM address (sender wallet)" },
+                    nonce: { type: "string", description: "Nonce from get_wallet_challenge" },
+                    signature: { type: "string", description: "Signature over the challenge message (personal_sign)" },
+                    chain: { type: "string", enum: ["base"], description: "Blockchain network (default: base)" },
+                },
+                required: ["wallet_address", "nonce", "signature"],
+            },
+        },
         {
             name: "fund_account",
             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.",
@@ -752,7 +820,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
         },
         {
             name: "request_payout",
-            description: "Request a payout of available earnings. Operators can withdraw via USDC on Base L2 through the operator portal or API.",
+            description: "Operator-only: agents cannot request payouts. Use this tool to understand payout options (withdrawals happen in the operator portal / operator API).",
             inputSchema: {
                 type: "object",
                 properties: { amount_usd: { type: "number", description: "Amount to withdraw in USD (min: $10)" } },
@@ -895,6 +963,60 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 }
                 return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
             }
+            case "register_agent": {
+                const parsed = RegisterAgentInputSchema.safeParse(args);
+                if (!parsed.success) {
+                    return {
+                        content: [{ type: "text", text: `Error: invalid input: ${parsed.error.message}` }],
+                        isError: true,
+                    };
+                }
+                try {
+                    const result = await apiRequest("/api/v1/agents/register", {
+                        method: "POST",
+                        body: JSON.stringify({
+                            name: parsed.data.name,
+                            email: parsed.data.email,
+                            ...(parsed.data.company ? { company: parsed.data.company } : {}),
+                        }),
+                    }, { auth: false });
+                    const apiKey = result && typeof result.api_key === "string" ? result.api_key : null;
+                    const banner = apiKey
+                        ? `CRITICAL — SAVE THIS API KEY:\nHUMANOPS_API_KEY=${apiKey}\n\nRestart your MCP server with this environment variable to use authenticated tools.`
+                        : "Registration succeeded.";
+                    return {
+                        content: [{ type: "text", text: `${banner}\n\n${JSON.stringify(result, null, 2)}` }],
+                    };
+                }
+                catch (err) {
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: `Error: ${err instanceof Error ? err.message : String(err)}\n\nTip: If you already registered with this email, use a different email address.`,
+                            },
+                        ],
+                        isError: true,
+                    };
+                }
+            }
+            case "get_agent_status": {
+                try {
+                    const result = await apiRequest("/api/v1/agents/status", { method: "GET" });
+                    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+                }
+                catch (err) {
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: `Error: ${err instanceof Error ? err.message : String(err)}\n\nIf you haven't registered yet, call register_agent first. Otherwise, set HUMANOPS_API_KEY and restart the MCP server.`,
+                            },
+                        ],
+                        isError: true,
+                    };
+                }
+            }
             case "check_verification_status": {
                 const parsed = GetTaskResultInputSchema.safeParse(args);
                 if (!parsed.success) {
@@ -920,13 +1042,80 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 const result = await apiRequest("/api/v1/agents/deposit-address", {
                     method: "GET",
                 });
+                const obj = result;
+                const walletVerified = Boolean(obj.wallet_verified);
+                const walletAddress = typeof obj.wallet_address === "string" ? obj.wallet_address : null;
+                const walletBound = walletVerified || Boolean(walletAddress);
+                const walletBindingRequired = Boolean(obj.wallet_verification?.required);
+                const instructions = walletBindingRequired
+                    ? (walletBound
+                        ? "Send USDC to this address, then call fund_account with payment_method='usdc', tx_hash, and chain to confirm the deposit."
+                        : "STEP 1: Call get_wallet_challenge to get a signing message. STEP 2: Sign the message with your wallet (personal_sign). STEP 3: Call bind_wallet with wallet_address + nonce + signature. STEP 4: Send USDC. STEP 5: Call fund_account with tx_hash + chain.")
+                    : (walletBound
+                        ? "Send USDC to this address, then call fund_account with tx_hash + chain to confirm the deposit."
+                        : "Wallet binding is optional in dev/test. For production parity, bind your wallet first: get_wallet_challenge → bind_wallet. Then send USDC and confirm via fund_account with tx_hash + chain.");
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                ...obj,
+                                wallet_bound: walletBound,
+                                wallet_binding_required: walletBindingRequired,
+                                _instructions: instructions,
+                            }, null, 2),
+                        },
+                    ],
+                };
+            }
+            case "get_wallet_challenge": {
+                const parsed = GetWalletChallengeInputSchema.safeParse(args ?? {});
+                if (!parsed.success) {
+                    return {
+                        content: [{ type: "text", text: `Error: invalid input: ${parsed.error.message}` }],
+                        isError: true,
+                    };
+                }
+                const result = await apiRequest("/api/v1/agents/wallet/challenge", {
+                    method: "POST",
+                    body: JSON.stringify({ chain: parsed.data.chain ?? "base" }),
+                });
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                ...result,
+                                _instructions: "Sign the returned message with your wallet using personal_sign. Then call bind_wallet with wallet_address + nonce + signature (and chain if needed).",
+                            }, null, 2),
+                        },
+                    ],
+                };
+            }
+            case "bind_wallet": {
+                const parsed = BindWalletInputSchema.safeParse(args);
+                if (!parsed.success) {
+                    return {
+                        content: [{ type: "text", text: `Error: invalid input: ${parsed.error.message}` }],
+                        isError: true,
+                    };
+                }
+                const result = await apiRequest("/api/v1/agents/wallet", {
+                    method: "PUT",
+                    body: JSON.stringify({
+                        wallet_address: parsed.data.wallet_address,
+                        nonce: parsed.data.nonce,
+                        signature: parsed.data.signature,
+                        chain: parsed.data.chain ?? "base",
+                    }),
+                });
                 return {
                     content: [
                         {
                             type: "text",
                             text: JSON.stringify({
                                 ...result,
-                                _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.",
+                                _instructions: "Wallet bound. You can now deposit USDC: call get_deposit_address, send USDC, then call fund_account with tx_hash + chain.",
                             }, null, 2),
                         },
                     ],
@@ -955,6 +1144,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                                 }, null, 2),
                             },
                         ],
+                        isError: true,
                     };
                 }
                 // USDC deposit verification
@@ -970,7 +1160,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                                 text: JSON.stringify({
                                     status: "awaiting_deposit",
                                     ...addressResult,
-                                    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.",
+                                    message: "No tx_hash provided. Send USDC to the address above. If the deposit response indicates wallet binding is required, bind your wallet first (get_wallet_challenge → bind_wallet). Then call fund_account again with tx_hash + chain to verify your deposit.",
                                 }, null, 2),
                             },
                         ],
@@ -1005,6 +1195,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                             }, null, 2),
                         },
                     ],
+                    isError: true,
                 };
             }
             case "get_balance": {
@@ -1186,17 +1377,22 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 const response = {
                     ...result,
                     private_key: keyPair.privateKey,
-                    _notice: "IMPORTANT: Save the private_key securely. You need it to decrypt the credential using retrieve_credential.",
+                    _notice: "Save the private_key securely. It is required to decrypt the credential using retrieve_credential. If lost, the credential is unrecoverable (single-read).",
                 };
+                const warningText = `CRITICAL — SAVE THIS PRIVATE KEY:\n` +
+                    `private_key: ${keyPair.privateKey}\n\n` +
+                    `You MUST store this key securely. It is required to decrypt the credential\n` +
+                    `via retrieve_credential. If lost, the credential is unrecoverable (single-read).\n\n` +
+                    `${JSON.stringify(response, null, 2)}`;
                 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)}` },
+                            { 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${warningText}` },
                         ],
                     };
                 }
-                return { content: [{ type: "text", text: JSON.stringify(response, null, 2) }] };
+                return { content: [{ type: "text", text: warningText }] };
             }
             case "retrieve_credential": {
                 const parsed = RetrieveCredentialInputSchema.safeParse(args);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@humanops/mcp-server",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "mcpName": "io.github.thepianistdirector/humanops",
   "description": "MCP server for AI agents to dispatch real-world tasks to verified human operators via HumanOps",
   "type": "module",