@humanops/mcp-server 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,1142 @@
+#!/usr/bin/env node
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import { z } from "zod";
+// ---------------------------------------------------------------------------
+// Local constants and helpers (keep MCP server standalone and Node-runnable).
+// ---------------------------------------------------------------------------
+const MIN_TASK_VALUE_USD = 10;
+const MAX_TASK_VALUE_USD = 10_000;
+const MIN_DEPOSIT_USD = 5;
+const MAX_DEPOSIT_USD = 10_000;
+const MIN_PAYOUT_USD = 10;
+const CREDENTIAL_CATEGORIES = [
+    "ACCOUNT_CREATION",
+    "API_KEY_PROCUREMENT",
+    "PHONE_VERIFICATION",
+    "SUBSCRIPTION_SETUP",
+];
+const DIGITAL_CATEGORY_CONFIG = {
+    CAPTCHA_SOLVING: {
+        maxValueUsd: 10,
+        defaultDeadlineMinutes: 15,
+        requiredProofTypes: ["SCREENSHOT"],
+        requiredTrustTier: "T1_STANDARD",
+        description: "Solve CAPTCHAs and visual challenges that AI cannot handle",
+    },
+    FORM_FILLING: {
+        maxValueUsd: 50,
+        defaultDeadlineMinutes: 60,
+        requiredProofTypes: ["SCREENSHOT", "CONFIRMATION"],
+        requiredTrustTier: "T1_STANDARD",
+        description: "Fill out web forms, applications, or registration flows",
+    },
+    BROWSER_INTERACTION: {
+        maxValueUsd: 100,
+        defaultDeadlineMinutes: 60,
+        requiredProofTypes: ["SCREENSHOT"],
+        requiredTrustTier: "T1_STANDARD",
+        description: "Perform browser-based interactions requiring human judgment",
+    },
+    CONTENT_REVIEW: {
+        maxValueUsd: 25,
+        defaultDeadlineMinutes: 120,
+        requiredProofTypes: ["CONFIRMATION"],
+        requiredTrustTier: "T1_STANDARD",
+        description: "Review and assess content for quality, accuracy, or compliance",
+    },
+    DATA_VALIDATION: {
+        maxValueUsd: 50,
+        defaultDeadlineMinutes: 120,
+        requiredProofTypes: ["CONFIRMATION"],
+        requiredTrustTier: "T1_STANDARD",
+        description: "Validate data accuracy by cross-referencing real-world sources",
+    },
+    ACCOUNT_CREATION: {
+        maxValueUsd: 100,
+        defaultDeadlineMinutes: 60,
+        requiredProofTypes: ["ARTIFACT", "SCREENSHOT"],
+        requiredTrustTier: "T2_DIGITAL",
+        description: "Create accounts on third-party services",
+    },
+    API_KEY_PROCUREMENT: {
+        maxValueUsd: 200,
+        defaultDeadlineMinutes: 120,
+        requiredProofTypes: ["ARTIFACT"],
+        requiredTrustTier: "T2_DIGITAL",
+        description: "Sign up and retrieve API keys from services",
+    },
+    PHONE_VERIFICATION: {
+        maxValueUsd: 25,
+        defaultDeadlineMinutes: 30,
+        requiredProofTypes: ["CONFIRMATION"],
+        requiredTrustTier: "T2_DIGITAL",
+        description: "Receive SMS codes and verify phone numbers",
+    },
+    SUBSCRIPTION_SETUP: {
+        maxValueUsd: 500,
+        defaultDeadlineMinutes: 120,
+        requiredProofTypes: ["ARTIFACT", "SCREENSHOT"],
+        requiredTrustTier: "T2_DIGITAL",
+        description: "Configure paid service subscriptions",
+    },
+};
+const DIGITAL_CATEGORIES = [
+    "CAPTCHA_SOLVING",
+    "FORM_FILLING",
+    "BROWSER_INTERACTION",
+    "CONTENT_REVIEW",
+    "DATA_VALIDATION",
+    "ACCOUNT_CREATION",
+    "API_KEY_PROCUREMENT",
+    "PHONE_VERIFICATION",
+    "SUBSCRIPTION_SETUP",
+];
+// ---------------------------------------------------------------------------
+// Inline E2EE helpers (ECDH P-256 + HKDF-SHA-256 + AES-256-GCM)
+// Inlined to keep MCP server standalone without importing @humanops/shared.
+// ---------------------------------------------------------------------------
+const HKDF_INFO = new TextEncoder().encode("humanops-credential-v1");
+function toBase64(buf) {
+    const bytes = new Uint8Array(buf);
+    let binary = "";
+    for (let i = 0; i < bytes.length; i++) {
+        binary += String.fromCharCode(bytes[i]);
+    }
+    return btoa(binary);
+}
+function fromBase64(b64) {
+    const binary = atob(b64);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++) {
+        bytes[i] = binary.charCodeAt(i);
+    }
+    return bytes.buffer;
+}
+async function generateKeyPair() {
+    const keyPair = await crypto.subtle.generateKey({ name: "ECDH", namedCurve: "P-256" }, true, ["deriveKey", "deriveBits"]);
+    const [publicRaw, privateRaw] = await Promise.all([
+        crypto.subtle.exportKey("raw", keyPair.publicKey),
+        crypto.subtle.exportKey("pkcs8", keyPair.privateKey),
+    ]);
+    return { publicKey: toBase64(publicRaw), privateKey: toBase64(privateRaw) };
+}
+async function importPublicKey(base64) {
+    return crypto.subtle.importKey("raw", fromBase64(base64), { name: "ECDH", namedCurve: "P-256" }, false, []);
+}
+async function importPrivateKey(base64) {
+    return crypto.subtle.importKey("pkcs8", fromBase64(base64), { name: "ECDH", namedCurve: "P-256" }, false, ["deriveBits"]);
+}
+async function deriveSharedSecret(privateKeyBase64, publicKeyBase64) {
+    const [privateKey, publicKey] = await Promise.all([
+        importPrivateKey(privateKeyBase64),
+        importPublicKey(publicKeyBase64),
+    ]);
+    const sharedBits = await crypto.subtle.deriveBits({ name: "ECDH", public: publicKey }, privateKey, 256);
+    const hkdfKey = await crypto.subtle.importKey("raw", sharedBits, "HKDF", false, ["deriveKey"]);
+    return crypto.subtle.deriveKey({ name: "HKDF", hash: "SHA-256", salt: new Uint8Array(32), info: HKDF_INFO }, hkdfKey, { name: "AES-GCM", length: 256 }, false, ["encrypt", "decrypt"]);
+}
+async function decryptCredential(encrypted, privateKeyBase64) {
+    const aesKey = await deriveSharedSecret(privateKeyBase64, encrypted.ephemeralPublicKey);
+    const plainBuf = await crypto.subtle.decrypt({ name: "AES-GCM", iv: fromBase64(encrypted.iv) }, aesKey, fromBase64(encrypted.ciphertext));
+    return new TextDecoder().decode(plainBuf);
+}
+// ---------------------------------------------------------------------------
+// SSRF protection
+// ---------------------------------------------------------------------------
+function isSSRFSafeUrl(urlStr, requireHttps = false) {
+    let parsed;
+    try {
+        parsed = new URL(urlStr);
+    }
+    catch {
+        return false;
+    }
+    if (!["http:", "https:"].includes(parsed.protocol))
+        return false;
+    if (requireHttps && parsed.protocol !== "https:")
+        return false;
+    const rawHostname = parsed.hostname.trim().toLowerCase().replace(/\.+$/, "");
+    if (!rawHostname)
+        return false;
+    const hostname = rawHostname.startsWith("[") && rawHostname.endsWith("]")
+        ? rawHostname.slice(1, -1)
+        : rawHostname;
+    if (hostname === "localhost" || hostname === "localhost.localdomain")
+        return false;
+    if (hostname.endsWith(".localhost"))
+        return false;
+    if (hostname.endsWith(".local") || hostname.endsWith(".localdomain"))
+        return false;
+    if (hostname === "metadata.google.internal")
+        return false;
+    if (hostname.endsWith(".internal"))
+        return false;
+    const ipv4 = parseIpv4(hostname);
+    if (ipv4 && isPrivateIpv4(ipv4))
+        return false;
+    const ipv6 = parseIpv6(hostname);
+    if (ipv6 && isPrivateIpv6(ipv6))
+        return false;
+    return true;
+}
+function parseIpv4(hostname) {
+    const dotted = hostname.match(/^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/);
+    if (dotted) {
+        const a = Number(dotted[1]);
+        const b = Number(dotted[2]);
+        const c = Number(dotted[3]);
+        const d = Number(dotted[4]);
+        if ([a, b, c, d].some((n) => !Number.isInteger(n) || n < 0 || n > 255))
+            return null;
+        return [a, b, c, d];
+    }
+    let n;
+    try {
+        if (/^0x[0-9a-f]+$/i.test(hostname)) {
+            n = BigInt(hostname);
+        }
+        else if (hostname === "0") {
+            n = 0n;
+        }
+        else if (/^0[0-7]+$/.test(hostname)) {
+            n = BigInt(`0o${hostname.slice(1)}`);
+        }
+        else if (/^\d+$/.test(hostname)) {
+            n = BigInt(hostname);
+        }
+        else {
+            return null;
+        }
+    }
+    catch {
+        return null;
+    }
+    if (n < 0n || n > 0xffffffffn)
+        return null;
+    const a = Number((n >> 24n) & 255n);
+    const b = Number((n >> 16n) & 255n);
+    const c = Number((n >> 8n) & 255n);
+    const d = Number(n & 255n);
+    return [a, b, c, d];
+}
+function isPrivateIpv4([a, b]) {
+    if (a === 127)
+        return true;
+    if (a === 10)
+        return true;
+    if (a === 172 && b >= 16 && b <= 31)
+        return true;
+    if (a === 192 && b === 168)
+        return true;
+    if (a === 169 && b === 254)
+        return true;
+    if (a === 100 && b >= 64 && b <= 127)
+        return true;
+    if (a === 0)
+        return true;
+    if (a === 198 && (b === 18 || b === 19))
+        return true;
+    if (a >= 224)
+        return true;
+    return false;
+}
+function parseIpv6(hostname) {
+    if (!hostname.includes(":"))
+        return null;
+    if (hostname.includes("%"))
+        return null;
+    const parts = hostname.split("::");
+    if (parts.length > 2)
+        return null;
+    const leftRaw = parts[0] ? parts[0].split(":") : [];
+    const rightRaw = parts.length === 2 && parts[1] ? parts[1].split(":") : [];
+    const left = [];
+    const right = [];
+    const pushToken = (arr, token) => {
+        if (!token)
+            return false;
+        if (token.includes(".")) {
+            const ipv4 = parseIpv4(token);
+            if (!ipv4)
+                return false;
+            arr.push((ipv4[0] << 8) | ipv4[1]);
+            arr.push((ipv4[2] << 8) | ipv4[3]);
+            return true;
+        }
+        if (!/^[0-9a-f]{1,4}$/i.test(token))
+            return false;
+        arr.push(parseInt(token, 16));
+        return true;
+    };
+    for (let i = 0; i < leftRaw.length; i++) {
+        if (!pushToken(left, leftRaw[i]))
+            return null;
+    }
+    for (let i = 0; i < rightRaw.length; i++) {
+        if (!pushToken(right, rightRaw[i]))
+            return null;
+    }
+    const total = left.length + right.length;
+    if (parts.length === 1) {
+        if (total !== 8)
+            return null;
+        return new Uint16Array([...left, ...right]);
+    }
+    if (total > 8)
+        return null;
+    const zerosToInsert = 8 - total;
+    return new Uint16Array([...left, ...Array(zerosToInsert).fill(0), ...right]);
+}
+function isPrivateIpv6(groups) {
+    if (groups.length !== 8)
+        return true;
+    if (groups.every((g) => g === 0))
+        return true;
+    if (groups[0] === 0 &&
+        groups[1] === 0 &&
+        groups[2] === 0 &&
+        groups[3] === 0 &&
+        groups[4] === 0 &&
+        groups[5] === 0 &&
+        groups[6] === 0 &&
+        groups[7] === 1) {
+        return true;
+    }
+    if ((groups[0] & 0xfe00) === 0xfc00)
+        return true;
+    if ((groups[0] & 0xffc0) === 0xfe80)
+        return true;
+    if ((groups[0] & 0xffc0) === 0xfec0)
+        return true;
+    if (groups[0] === 0 &&
+        groups[1] === 0 &&
+        groups[2] === 0 &&
+        groups[3] === 0 &&
+        groups[4] === 0 &&
+        groups[5] === 0xffff) {
+        const a = (groups[6] >> 8) & 0xff;
+        const b = groups[6] & 0xff;
+        const c = (groups[7] >> 8) & 0xff;
+        const d = groups[7] & 0xff;
+        return isPrivateIpv4([a, b, c, d]);
+    }
+    return false;
+}
+/**
+ * HumanOps MCP Server (safe mode)
+ *
+ * Design: This MCP server is a local process. To avoid bypassing the API's
+ * authz/rate-limits/audit logging, it talks to HumanOps via HTTP only.
+ */
+const DEFAULT_API_URL = "https://api.humanops.io";
+function getApiUrl() {
+    const raw = process.env.HUMANOPS_API_URL?.trim();
+    if (!raw)
+        return DEFAULT_API_URL;
+    const url = raw.replace(/\/+$/, "");
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        throw new Error("HUMANOPS_API_URL must be a valid URL.");
+    }
+    const allowAnyHost = process.env.HUMANOPS_ALLOW_ANY_API_HOST === "true";
+    const hostname = parsed.hostname.trim().toLowerCase().replace(/\.+$/, "");
+    if (!allowAnyHost) {
+        // 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.");
+        }
+    }
+    // Prevent subtle base URL bugs like including paths, querystrings, or fragments.
+    if (parsed.pathname && parsed.pathname !== "/") {
+        throw new Error("HUMANOPS_API_URL must not include a path (use only the origin, e.g. https://api.humanops.io).");
+    }
+    if (parsed.search || parsed.hash) {
+        throw new Error("HUMANOPS_API_URL must not include query params or a fragment.");
+    }
+    const normalized = parsed.origin;
+    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;
+    if (!apiKey) {
+        throw new Error("HUMANOPS_API_KEY environment variable is required.");
+    }
+    return apiKey;
+}
+async function apiRequest(path, init = {}) {
+    const baseUrl = getApiUrl();
+    const apiKey = getApiKey();
+    const url = `${baseUrl}${path}`;
+    const headers = new Headers(init.headers);
+    headers.set("X-API-Key", apiKey);
+    if (!headers.has("Content-Type") && init.body && typeof init.body === "string") {
+        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 contentType = res.headers.get("content-type") ?? "";
+    const raw = await res.text();
+    const json = contentType.includes("application/json") && raw ? JSON.parse(raw) : null;
+    if (!res.ok) {
+        const message = json?.error ||
+            json?.message ||
+            res.statusText ||
+            `HTTP ${res.status}`;
+        throw new Error(message);
+    }
+    return (json ?? raw);
+}
+// ---------------------------------------------------------------------------
+// Tool schemas (validate inputs before hitting the API)
+// ---------------------------------------------------------------------------
+const TaskTypeEnum = z.enum([
+    "VERIFICATION",
+    "PHOTO",
+    "DELIVERY",
+    "INSPECTION",
+    "CAPTCHA_SOLVING",
+    "FORM_FILLING",
+    "BROWSER_INTERACTION",
+    "CONTENT_REVIEW",
+    "DATA_VALIDATION",
+    "ACCOUNT_CREATION",
+    "API_KEY_PROCUREMENT",
+    "PHONE_VERIFICATION",
+    "SUBSCRIPTION_SETUP",
+]);
+const DigitalCategoryEnum = z.enum([
+    "CAPTCHA_SOLVING",
+    "FORM_FILLING",
+    "BROWSER_INTERACTION",
+    "CONTENT_REVIEW",
+    "DATA_VALIDATION",
+]);
+const CredentialCategoryEnum = z.enum([
+    "ACCOUNT_CREATION",
+    "API_KEY_PROCUREMENT",
+    "PHONE_VERIFICATION",
+    "SUBSCRIPTION_SETUP",
+]);
+const DispatchDigitalTaskInputSchema = z.object({
+    title: z.string().min(1).max(200),
+    description: z.string().min(10).max(5000),
+    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),
+    digital_instructions: z.string().max(5000).optional(),
+    callback_url: z
+        .string()
+        .url()
+        .refine((url) => isSSRFSafeUrl(url, true), {
+        message: "callback_url must be a public HTTPS URL (private/internal addresses are blocked)",
+    })
+        .optional(),
+    callback_secret: z.string().min(16).max(128).optional(),
+    idempotency_key: z.string().min(1).max(200).optional(),
+});
+const DispatchCredentialTaskInputSchema = z.object({
+    title: z.string().min(1).max(200),
+    description: z.string().min(10).max(5000),
+    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),
+    digital_instructions: z.string().max(5000).optional(),
+    callback_url: z
+        .string()
+        .url()
+        .refine((url) => isSSRFSafeUrl(url, true), {
+        message: "callback_url must be a public HTTPS URL (private/internal addresses are blocked)",
+    })
+        .optional(),
+    callback_secret: z.string().min(16).max(128).optional(),
+    idempotency_key: z.string().min(1).max(200).optional(),
+});
+const RetrieveCredentialInputSchema = z.object({
+    task_id: z.string().min(1),
+    private_key: z.string().min(1),
+});
+const SearchOperatorsInputSchema = z.object({
+    lat: z.number(),
+    lng: z.number(),
+    radius_km: z.number().min(1).max(500).optional(),
+    task_type: TaskTypeEnum.optional(),
+    min_rating: z.number().min(0).max(5).optional(),
+});
+const PostTaskInputSchema = z.object({
+    title: z.string().min(1).max(200),
+    description: z.string().min(10).max(5000),
+    location: z.object({
+        lat: z.number(),
+        lng: z.number(),
+        address: z.string().min(1),
+    }),
+    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),
+    task_type: TaskTypeEnum,
+    callback_url: z
+        .string()
+        .url()
+        .refine((url) => isSSRFSafeUrl(url, true), {
+        message: "callback_url must be a public HTTPS URL (private/internal addresses are blocked)",
+    })
+        .optional(),
+    callback_secret: z.string().min(16).max(128).optional(),
+    idempotency_key: z.string().min(1).max(200).optional(),
+});
+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(),
+    return_url: z
+        .string()
+        .url()
+        .refine((url) => isSSRFSafeUrl(url, true), {
+        message: "return_url must be a public HTTPS URL (private/internal addresses are blocked)",
+    })
+        .optional(),
+});
+const RequestPayoutInputSchema = z.object({
+    amount_usd: z.number().min(MIN_PAYOUT_USD),
+});
+const ALL_TASK_TYPES = [
+    "VERIFICATION", "PHOTO", "DELIVERY", "INSPECTION",
+    "CAPTCHA_SOLVING", "FORM_FILLING", "BROWSER_INTERACTION", "CONTENT_REVIEW", "DATA_VALIDATION",
+    "ACCOUNT_CREATION", "API_KEY_PROCUREMENT", "PHONE_VERIFICATION", "SUBSCRIPTION_SETUP",
+];
+const server = new Server({
+    name: "humanops",
+    version: "0.2.0",
+}, {
+    capabilities: { tools: {} },
+});
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: [
+        {
+            name: "search_operators",
+            description: "Search for available human operators near a location who can perform real-world tasks like verifications, photo documentation, deliveries, and inspections.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    lat: { type: "number", description: "Latitude of the task location" },
+                    lng: { type: "number", description: "Longitude of the task location" },
+                    radius_km: { type: "number", description: "Search radius in kilometers (default: 50, max: 500)", default: 50 },
+                    task_type: {
+                        type: "string",
+                        enum: [...ALL_TASK_TYPES],
+                    },
+                    min_rating: { type: "number", description: "Minimum operator rating (0-5)" },
+                },
+                required: ["lat", "lng"],
+            },
+        },
+        {
+            name: "post_task",
+            description: "Create a new task for a human operator. Supports physical tasks (VERIFICATION, PHOTO, DELIVERY, INSPECTION), digital tasks (CAPTCHA_SOLVING, FORM_FILLING, etc.), and credential tasks (ACCOUNT_CREATION, API_KEY_PROCUREMENT, etc.). For digital tasks prefer dispatch_digital_task; for credential tasks prefer dispatch_credential_task. Funds will be escrowed from your account (reward + platform fee).",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    title: { type: "string" },
+                    description: { type: "string" },
+                    location: {
+                        type: "object",
+                        properties: { lat: { type: "number" }, lng: { type: "number" }, address: { type: "string" } },
+                        required: ["lat", "lng", "address"],
+                    },
+                    reward_usd: { type: "number" },
+                    deadline: { type: "string", description: "ISO 8601 deadline for task completion" },
+                    proof_requirements: { type: "array", items: { type: "string" } },
+                    task_type: {
+                        type: "string",
+                        enum: [...ALL_TASK_TYPES],
+                    },
+                    callback_url: { type: "string" },
+                    callback_secret: { type: "string", description: "Optional secret to sign webhook callbacks" },
+                    idempotency_key: { type: "string", description: "Optional key to make task creation safe to retry" },
+                },
+                required: ["title", "description", "location", "reward_usd", "deadline", "proof_requirements", "task_type"],
+            },
+        },
+        {
+            name: "dispatch_digital_task",
+            description: "Create a Tier 1 digital task for a human operator. Includes CAPTCHA solving, form filling, browser interaction, content review, and data validation. No physical location needed — operators complete these tasks remotely.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    title: { type: "string", description: "Short title for the task" },
+                    description: { type: "string", description: "Detailed description of what needs to be done" },
+                    digital_category: {
+                        type: "string",
+                        enum: ["CAPTCHA_SOLVING", "FORM_FILLING", "BROWSER_INTERACTION", "CONTENT_REVIEW", "DATA_VALIDATION"],
+                        description: "Category of digital task",
+                    },
+                    reward_usd: { type: "number", description: "Reward in USD for the operator" },
+                    deadline: { type: "string", description: "ISO 8601 deadline for task completion" },
+                    proof_requirements: {
+                        type: "array",
+                        items: { type: "string" },
+                        description: "List of proof requirements",
+                    },
+                    digital_instructions: {
+                        type: "string",
+                        description: "Specific step-by-step instructions for the digital task",
+                    },
+                    callback_url: { type: "string", description: "Optional webhook URL for status updates" },
+                    callback_secret: { type: "string", description: "Optional secret to sign webhook callbacks" },
+                    idempotency_key: { type: "string", description: "Optional key to make task creation safe to retry" },
+                },
+                required: ["title", "description", "digital_category", "reward_usd", "deadline", "proof_requirements"],
+            },
+        },
+        {
+            name: "dispatch_credential_task",
+            description: "Create a task requiring a human operator to deliver credentials (account login, API key, phone verification code, etc.) via an end-to-end encrypted channel. A unique ECDH keypair is generated automatically — only you can decrypt the result. The server never sees plaintext credentials. IMPORTANT: Save the returned private_key — you need it to call retrieve_credential later.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    title: { type: "string", description: "Short title for the credential task" },
+                    description: { type: "string", description: "Detailed description of what credentials are needed" },
+                    digital_category: {
+                        type: "string",
+                        enum: ["ACCOUNT_CREATION", "API_KEY_PROCUREMENT", "PHONE_VERIFICATION", "SUBSCRIPTION_SETUP"],
+                        description: "Category of credential task",
+                    },
+                    reward_usd: { type: "number", description: "Reward in USD for the operator" },
+                    deadline: { type: "string", description: "ISO 8601 deadline for task completion" },
+                    proof_requirements: {
+                        type: "array",
+                        items: { type: "string" },
+                        description: "List of proof requirements (e.g., 'screenshot of account creation')",
+                    },
+                    digital_instructions: {
+                        type: "string",
+                        description: "Step-by-step instructions for the operator",
+                    },
+                    callback_url: { type: "string", description: "Optional webhook URL for status updates" },
+                    callback_secret: { type: "string", description: "Optional secret to sign webhook callbacks" },
+                    idempotency_key: { type: "string", description: "Optional key to make task creation safe to retry" },
+                },
+                required: ["title", "description", "digital_category", "reward_usd", "deadline", "proof_requirements"],
+            },
+        },
+        {
+            name: "retrieve_credential",
+            description: "Retrieve and decrypt the credential delivered by a human operator for a completed Tier 2 task. Requires the private_key returned by dispatch_credential_task. The decryption happens locally — the server never sees the plaintext.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    task_id: { type: "string", description: "The task ID from dispatch_credential_task" },
+                    private_key: { type: "string", description: "The base64-encoded private key returned by dispatch_credential_task" },
+                },
+                required: ["task_id", "private_key"],
+            },
+        },
+        {
+            name: "list_digital_categories",
+            description: "List available digital task categories with descriptions, pricing, and trust tier requirements. Returns both Tier 1 (standard digital) and Tier 2 (credential) categories.",
+            inputSchema: {
+                type: "object",
+                properties: {},
+                required: [],
+            },
+        },
+        {
+            name: "get_task_result",
+            description: "Get the current status, proof, and AI Guardian verification result for a task.",
+            inputSchema: {
+                type: "object",
+                properties: { task_id: { type: "string" } },
+                required: ["task_id"],
+            },
+        },
+        {
+            name: "check_verification_status",
+            description: "Check the AI Guardian verification status and result for a task. Returns focused verification details including decision and confidence.",
+            inputSchema: {
+                type: "object",
+                properties: { task_id: { type: "string" } },
+                required: ["task_id"],
+            },
+        },
+        {
+            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.",
+            inputSchema: {
+                type: "object",
+                properties: {},
+                required: [],
+            },
+        },
+        {
+            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.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    amount_usd: { type: "number", description: "Amount in USD (min: $5, max: $10,000). For USDC deposits, this is the expected amount." },
+                    payment_method: {
+                        type: "string",
+                        enum: ["usdc", "card", "bank_transfer"],
+                        description: "Payment method. Defaults to 'usdc'. Card and bank_transfer are coming soon.",
+                        default: "usdc",
+                    },
+                    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.",
+                    },
+                    return_url: { type: "string", description: "Optional return URL after fiat payment (not used for USDC)" },
+                },
+                required: ["amount_usd"],
+            },
+        },
+        {
+            name: "request_payout",
+            description: "Request a payout of available earnings. Currently only available through the HumanOps operator portal.",
+            inputSchema: {
+                type: "object",
+                properties: { amount_usd: { type: "number", description: "Amount to withdraw in USD (min: $10)" } },
+                required: ["amount_usd"],
+            },
+        },
+        {
+            name: "get_balance",
+            description: "Check your HumanOps account balances. Returns deposit balance (available to create tasks) and escrow balance (locked in active tasks).",
+            inputSchema: {
+                type: "object",
+                properties: {},
+                required: [],
+            },
+        },
+        {
+            name: "cancel_task",
+            description: "Cancel a pending or accepted task. The escrowed funds (reward + platform fee) will be refunded to your account.",
+            inputSchema: {
+                type: "object",
+                properties: { task_id: { type: "string", description: "The task ID to cancel" } },
+                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)" },
+                    limit: { type: "number", description: "Max results (default: 20, max: 100)" },
+                    offset: { type: "number", description: "Pagination offset (default: 0)" },
+                },
+            },
+        },
+    ],
+}));
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    try {
+        switch (name) {
+            case "search_operators": {
+                const parsed = SearchOperatorsInputSchema.safeParse(args);
+                if (!parsed.success) {
+                    return {
+                        content: [{ type: "text", text: `Error: invalid input: ${parsed.error.message}` }],
+                        isError: true,
+                    };
+                }
+                const { lat, lng, radius_km, task_type, min_rating } = parsed.data;
+                const data = await apiRequest("/api/v1/operators/search", {
+                    method: "POST",
+                    body: JSON.stringify({
+                        location: { lat, lng },
+                        radius_km,
+                        task_type,
+                        min_rating,
+                    }),
+                });
+                return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+            }
+            case "post_task": {
+                const parsed = PostTaskInputSchema.safeParse(args);
+                if (!parsed.success) {
+                    return {
+                        content: [{ type: "text", text: `Error: invalid input: ${parsed.error.message}` }],
+                        isError: true,
+                    };
+                }
+                const sandbox = process.env.HUMANOPS_SANDBOX === "true";
+                const headers = {};
+                if (sandbox) {
+                    headers["X-Sandbox-Mode"] = "true";
+                }
+                const { idempotency_key, ...body } = parsed.data;
+                if (idempotency_key)
+                    headers["Idempotency-Key"] = idempotency_key;
+                const result = await apiRequest("/api/v1/tasks", {
+                    method: "POST",
+                    body: JSON.stringify(body),
+                    headers,
+                });
+                return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+            }
+            case "get_task_result": {
+                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)}`, {
+                    method: "GET",
+                });
+                return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+            }
+            case "check_verification_status": {
+                const parsed = GetTaskResultInputSchema.safeParse(args);
+                if (!parsed.success) {
+                    return {
+                        content: [{ type: "text", text: `Error: invalid input: ${parsed.error.message}` }],
+                        isError: true,
+                    };
+                }
+                const task = await apiRequest(`/api/v1/tasks/${encodeURIComponent(parsed.data.task_id)}`, {
+                    method: "GET",
+                });
+                const focused = {
+                    task_id: task.task_id ?? parsed.data.task_id,
+                    status: task.status,
+                    guardian_result: task.guardian_result,
+                    verified_at: task.verified_at ?? null,
+                    completed_at: task.completed_at ?? null,
+                };
+                return { content: [{ type: "text", text: JSON.stringify(focused, null, 2) }] };
+            }
+            case "get_deposit_address": {
+                const result = await apiRequest("/api/v1/agents/deposit-address", {
+                    method: "GET",
+                });
+                return {
+                    content: [
+                        {
+                            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.",
+                            }, null, 2),
+                        },
+                    ],
+                };
+            }
+            case "fund_account": {
+                const parsed = FundAccountInputSchema.safeParse(args);
+                if (!parsed.success) {
+                    return {
+                        content: [{ type: "text", text: `Error: invalid input: ${parsed.error.message}` }],
+                        isError: true,
+                    };
+                }
+                const { amount_usd, payment_method, tx_hash, chain, return_url } = parsed.data;
+                const method = payment_method ?? "usdc";
+                // Fiat methods are coming soon
+                if (method === "card" || method === "bank_transfer") {
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: JSON.stringify({
+                                    status: "coming_soon",
+                                    payment_method: method,
+                                    amount_usd,
+                                    message: `Fiat deposits via ${method} are coming soon. Use USDC deposits instead — call get_deposit_address to get your deposit address, send USDC, then call fund_account with payment_method='usdc', tx_hash, and chain.`,
+                                }, null, 2),
+                            },
+                        ],
+                    };
+                }
+                // USDC deposit verification
+                if (!tx_hash) {
+                    // No tx_hash — return deposit address instructions
+                    const addressResult = await apiRequest("/api/v1/agents/deposit-address", {
+                        method: "GET",
+                    });
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                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.",
+                                }, null, 2),
+                            },
+                        ],
+                    };
+                }
+                const result = await apiRequest("/api/v1/agents/deposit/usdc", {
+                    method: "POST",
+                    body: JSON.stringify({
+                        amount_usd,
+                        tx_hash,
+                        chain: chain ?? "base",
+                    }),
+                });
+                return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+            }
+            case "request_payout": {
+                const parsed = RequestPayoutInputSchema.safeParse(args);
+                if (!parsed.success) {
+                    return {
+                        content: [{ type: "text", text: `Error: invalid input: ${parsed.error.message}` }],
+                        isError: true,
+                    };
+                }
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                status: "unavailable",
+                                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.",
+                            }, null, 2),
+                        },
+                    ],
+                };
+            }
+            case "get_balance": {
+                const data = await apiRequest("/api/v1/agents/balance", { method: "GET" });
+                return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+            }
+            case "cancel_task": {
+                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)}/cancel`, {
+                    method: "POST",
+                });
+                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 query = params.toString();
+                const data = await apiRequest(`/api/v1/tasks${query ? `?${query}` : ""}`, { method: "GET" });
+                return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+            }
+            case "dispatch_digital_task": {
+                const parsed = DispatchDigitalTaskInputSchema.safeParse(args);
+                if (!parsed.success) {
+                    return {
+                        content: [{ type: "text", text: `Error: invalid input: ${parsed.error.message}` }],
+                        isError: true,
+                    };
+                }
+                const { digital_category, digital_instructions, idempotency_key, ...rest } = parsed.data;
+                const categoryConfig = DIGITAL_CATEGORY_CONFIG[digital_category];
+                if (categoryConfig && rest.reward_usd > categoryConfig.maxValueUsd) {
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: `Error: reward_usd ($${rest.reward_usd}) exceeds max for ${digital_category} ($${categoryConfig.maxValueUsd})`,
+                            },
+                        ],
+                        isError: true,
+                    };
+                }
+                const sandbox = process.env.HUMANOPS_SANDBOX === "true";
+                const headers = {};
+                if (sandbox) {
+                    headers["X-Sandbox-Mode"] = "true";
+                }
+                if (idempotency_key)
+                    headers["Idempotency-Key"] = idempotency_key;
+                const payload = {
+                    ...rest,
+                    task_type: digital_category,
+                    task_domain: "DIGITAL",
+                    location: { lat: 0, lng: 0, address: "Remote/Digital" },
+                    ...(digital_instructions ? { digital_instructions } : {}),
+                };
+                const result = await apiRequest("/api/v1/tasks", {
+                    method: "POST",
+                    body: JSON.stringify(payload),
+                    headers,
+                });
+                return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+            }
+            case "dispatch_credential_task": {
+                const parsed = DispatchCredentialTaskInputSchema.safeParse(args);
+                if (!parsed.success) {
+                    return {
+                        content: [{ type: "text", text: `Error: invalid input: ${parsed.error.message}` }],
+                        isError: true,
+                    };
+                }
+                const { digital_category, digital_instructions, idempotency_key, ...rest } = parsed.data;
+                const credCategoryConfig = DIGITAL_CATEGORY_CONFIG[digital_category];
+                if (credCategoryConfig && rest.reward_usd > credCategoryConfig.maxValueUsd) {
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: `Error: reward_usd ($${rest.reward_usd}) exceeds max for ${digital_category} ($${credCategoryConfig.maxValueUsd})`,
+                            },
+                        ],
+                        isError: true,
+                    };
+                }
+                // Generate ECDH keypair for E2EE credential delivery
+                const keyPair = await generateKeyPair();
+                const sandbox = process.env.HUMANOPS_SANDBOX === "true";
+                const headers = {};
+                if (sandbox) {
+                    headers["X-Sandbox-Mode"] = "true";
+                }
+                if (idempotency_key)
+                    headers["Idempotency-Key"] = idempotency_key;
+                const payload = {
+                    ...rest,
+                    task_type: digital_category,
+                    task_domain: "DIGITAL",
+                    location: { lat: 0, lng: 0, address: "Remote/Digital" },
+                    agent_public_key: keyPair.publicKey,
+                    ...(digital_instructions ? { digital_instructions } : {}),
+                };
+                const result = await apiRequest("/api/v1/tasks", {
+                    method: "POST",
+                    body: JSON.stringify(payload),
+                    headers,
+                });
+                const response = {
+                    ...result,
+                    private_key: keyPair.privateKey,
+                    _notice: "IMPORTANT: Save the private_key securely. You need it to decrypt the credential using retrieve_credential.",
+                };
+                return { content: [{ type: "text", text: JSON.stringify(response, null, 2) }] };
+            }
+            case "retrieve_credential": {
+                const parsed = RetrieveCredentialInputSchema.safeParse(args);
+                if (!parsed.success) {
+                    return {
+                        content: [{ type: "text", text: `Error: invalid input: ${parsed.error.message}` }],
+                        isError: true,
+                    };
+                }
+                const { task_id, private_key } = parsed.data;
+                // Use the single-read POST endpoint (server clears credential after retrieval)
+                let retrieveResult;
+                try {
+                    retrieveResult = await apiRequest(`/api/v1/tasks/${encodeURIComponent(task_id)}/retrieve-credential`, {
+                        method: "POST",
+                        body: JSON.stringify({}),
+                    });
+                }
+                catch (retrieveErr) {
+                    // If no credential available, provide a helpful error
+                    if (retrieveErr.message?.includes("No encrypted credential")) {
+                        const task = await apiRequest(`/api/v1/tasks/${encodeURIComponent(task_id)}`, { method: "GET" });
+                        return {
+                            content: [
+                                {
+                                    type: "text",
+                                    text: JSON.stringify({
+                                        task_id,
+                                        status: task.status,
+                                        error: "No encrypted credential available yet. The operator may not have submitted it, or the task is not in a completed state.",
+                                    }, null, 2),
+                                },
+                            ],
+                            isError: true,
+                        };
+                    }
+                    throw retrieveErr;
+                }
+                const plaintext = await decryptCredential(retrieveResult.encrypted_credential, private_key);
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                task_id,
+                                credential: plaintext,
+                                retrieved_at: retrieveResult.retrieved_at,
+                                _notice: "This credential was decrypted locally. The HumanOps server never saw the plaintext. The encrypted credential has been cleared from the server (single-read).",
+                            }, null, 2),
+                        },
+                    ],
+                };
+            }
+            case "list_digital_categories": {
+                const categories = DIGITAL_CATEGORIES.map((cat) => {
+                    const config = DIGITAL_CATEGORY_CONFIG[cat];
+                    return {
+                        category: cat,
+                        tier: config.requiredTrustTier,
+                        description: config.description,
+                        maxValueUsd: config.maxValueUsd,
+                        defaultDeadlineMinutes: config.defaultDeadlineMinutes,
+                        requiredProofTypes: config.requiredProofTypes,
+                        isCredentialTask: CREDENTIAL_CATEGORIES.includes(cat),
+                    };
+                });
+                return { content: [{ type: "text", text: JSON.stringify(categories, null, 2) }] };
+            }
+            default:
+                return { content: [{ type: "text", text: `Unknown tool: ${name}` }], isError: true };
+        }
+    }
+    catch (err) {
+        const errorMessage = err.message || "Unknown error";
+        const isNetworkError = errorMessage.includes("fetch failed") || errorMessage.includes("ECONNREFUSED");
+        const hint = isNetworkError
+            ? " (Network error — check your HUMANOPS_API_URL and HUMANOPS_API_KEY configuration.)"
+            : "";
+        return {
+            content: [{ type: "text", text: `Error: ${errorMessage}${hint}` }],
+            isError: true,
+        };
+    }
+});
+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");
+    }
+}
+main().catch((err) => {
+    console.error("Failed to start MCP server:", err);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@humanops/mcp-server",
+  "version": "0.2.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"
+  },
+  "files": ["dist/*.js", "dist/*.d.ts"],
+  "scripts": {
+    "start": "node dist/index.js",
+    "dev": "tsx watch src/index.ts",
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "lint": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "tsx": "^4.19.0",
+    "typescript": "^5.7.0"
+  },
+  "license": "MIT",
+  "keywords": ["humanops", "mcp", "ai", "agents", "tasks", "model-context-protocol"],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ThePianistDirector/real-auto-code"
+  }
+}