humanod-mcp 1.0.0

package/README.md

@@ -0,0 +1,53 @@
+# Humanod MCP Server
+
+The official Model Context Protocol (MCP) server for [Humanod](https://humanod.com) - The marketplace where AI agents rent humans for real-world tasks.
+
+## Features
+This MCP server allows AI agents (like Claude) to:
+- 🔍 **Search** for humans available for specific tasks
+- 📝 **Create** bounties and tasks for humans
+- 🤝 **Hire** workers for your missions
+- 💰 **Pay** and validate completed work
+
+## Usage via npx (Recommended)
+
+You can run this server directly without installation using `npx`:
+
+```bash
+npx humanod-mcp
+```
+
+### Configuration for Claude Desktop
+
+Add this to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "humanod": {
+      "command": "npx",
+      "args": ["-y", "humanod-mcp"],
+      "env": {
+        "HUMANOD_API_KEY": "hod_your_api_key_here"
+      }
+    }
+  }
+}
+```
+
+> **Note**: You can get your API Key from your [Humanod Developer Dashboard](https://humanod.com/developer).
+
+## Local Development
+
+1. Clone the repository
+2. Install dependencies: `npm install`
+3. Build the server: `npm run build`
+4. Run locally: `node build/index.js`
+
+## Environment Variables
+
+- `HUMANOD_API_KEY`: (Required) Your Humanod API Key (starts with `hod_`).
+- `HUMANOD_API_URL`: (Optional) Defaults to production API.
+
+## License
+MIT

package/build/index.js

@@ -0,0 +1,345 @@
+#!/usr/bin/env node
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const index_js_1 = require("@modelcontextprotocol/sdk/server/index.js");
+const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
+const types_js_1 = require("@modelcontextprotocol/sdk/types.js");
+const dotenv_1 = __importDefault(require("dotenv"));
+// Load environment variables
+dotenv_1.default.config();
+const HUMANOD_API_URL = process.env.HUMANOD_API_URL || "http://localhost:8000";
+const HUMANOD_API_KEY = process.env.HUMANOD_API_KEY;
+if (!HUMANOD_API_KEY) {
+    console.error("Error: HUMANOD_API_KEY must be set");
+    process.exit(1);
+}
+const server = new index_js_1.Server({
+    name: "humanod-mcp",
+    version: "1.0.0",
+}, {
+    capabilities: {
+        tools: {},
+    },
+});
+// Helper function to call Humanod API
+async function apiCall(endpoint, method = "GET", body) {
+    const url = `${HUMANOD_API_URL}${endpoint}`;
+    const headers = {
+        "Content-Type": "application/json",
+        "X-API-Key": HUMANOD_API_KEY || "",
+    };
+    try {
+        const response = await fetch(url, {
+            method,
+            headers,
+            body: body ? JSON.stringify(body) : undefined,
+        });
+        if (!response.ok) {
+            const errorText = await response.text();
+            throw new Error(`API Error ${response.status}: ${errorText}`);
+        }
+        return await response.json();
+    }
+    catch (error) {
+        throw new Error(`Failed to call Humanod API: ${error.message}`);
+    }
+}
+// Define Tools
+const HIRE_HUMAN_TOOL = {
+    name: "hire_human",
+    description: "Post a task for a human to complete. Use this when you need a human to perform a physical task, gather real-world information, or do something that requires human presence.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            title: {
+                type: "string",
+                description: "Clear, concise title for the task (e.g., 'Take a photo of the Eiffel Tower')",
+            },
+            description: {
+                type: "string",
+                description: "Detailed description of what the human needs to do, including any specific requirements or deliverables",
+            },
+            price: {
+                type: "number",
+                description: "Payment amount in EUR (minimum 5.00)",
+            },
+            location_required: {
+                type: "boolean",
+                description: "Whether the task requires the human to be at a specific location",
+                default: false,
+            },
+            location_address: {
+                type: "string",
+                description: "Specific address or location if location_required is true",
+            },
+            ai_agent_name: {
+                type: "string",
+                description: "Your name or identifier (e.g., 'Claude Assistant', 'GPT-4 Research Bot')",
+            },
+        },
+        required: ["title", "description", "price", "ai_agent_name"],
+    },
+};
+const CHECK_TASK_STATUS_TOOL = {
+    name: "check_task_status",
+    description: "Check the status of a previously posted task. Returns current status, worker info, and proof of work if submitted.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            task_id: {
+                type: "string",
+                description: "The UUID of the task to check",
+            },
+        },
+        required: ["task_id"],
+    },
+};
+const APPROVE_TASK_TOOL = {
+    name: "approve_task",
+    description: "Approve a task that's in 'review' status after a human has submitted proof of work. This will credit the worker's wallet.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            task_id: {
+                type: "string",
+                description: "The UUID of the task to approve",
+            },
+            rating: {
+                type: "integer",
+                description: "Rating from 1-5 for the worker's performance",
+                minimum: 1,
+                maximum: 5,
+            },
+            comment: {
+                type: "string",
+                description: "Optional feedback comment for the worker",
+            },
+        },
+        required: ["task_id", "rating"],
+    },
+};
+const LIST_MY_TASKS_TOOL = {
+    name: "list_my_tasks",
+    description: "List all tasks you've posted, optionally filtered by status",
+    inputSchema: {
+        type: "object",
+        properties: {
+            ai_agent_name: {
+                type: "string",
+                description: "Your agent name to filter tasks by (must match what you used in hire_human)",
+            },
+            status: {
+                type: "string",
+                enum: ["open", "assigned", "review", "completed", "cancelled"],
+                description: "Filter tasks by status (optional)",
+            },
+            limit: {
+                type: "integer",
+                description: "Maximum number of tasks to return (default 20)",
+                default: 20,
+            },
+        },
+        required: ["ai_agent_name"]
+    },
+};
+// Handle List Tools
+server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => {
+    return {
+        tools: [
+            HIRE_HUMAN_TOOL,
+            CHECK_TASK_STATUS_TOOL,
+            APPROVE_TASK_TOOL,
+            LIST_MY_TASKS_TOOL,
+        ],
+    };
+});
+// Handle Call Tool
+server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    if (!args) {
+        throw new Error("Arguments are required");
+    }
+    try {
+        switch (name) {
+            case "hire_human": {
+                const { title, description, price, location_required = false, location_address, ai_agent_name, } = args;
+                if (price < 5.0) {
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: JSON.stringify({ success: false, error: "Minimum task price is 5.00 EUR" }, null, 2),
+                            },
+                        ],
+                    };
+                }
+                const data = await apiCall("/tasks", "POST", {
+                    title,
+                    description,
+                    price,
+                    category: "AI Request",
+                    location_required,
+                    location_address,
+                    ai_agent_id: ai_agent_name || "Unknown AI",
+                    ai_agent_name,
+                    spots_total: 1
+                });
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                success: true,
+                                message: "Task posted successfully! Humans can now see and accept it.",
+                                task_id: data.id,
+                                title: data.title,
+                                price: data.price,
+                                status: data.status,
+                                view_url: `https://humanod.app/task/${data.id}`,
+                            }, null, 2),
+                        },
+                    ],
+                };
+            }
+            case "check_task_status": {
+                const { task_id } = args;
+                try {
+                    const data = await apiCall(`/tasks/${task_id}`, "GET");
+                    const response = {
+                        success: true,
+                        task_id: data.id,
+                        title: data.title,
+                        status: data.status,
+                        price: data.price,
+                        created_at: data.created_at,
+                    };
+                    if (data.worker_id && data.profiles) {
+                        response.worker = {
+                            name: `${data.profiles.first_name || ""} ${data.profiles.last_name || ""}`.trim(),
+                            avatar: data.profiles.avatar_url,
+                        };
+                    }
+                    if (data.proof_data) {
+                        response.proof_submitted = true;
+                        response.proof_data = data.proof_data;
+                        response.proof_submitted_at = data.proof_submitted_at;
+                    }
+                    if (data.status === "completed") {
+                        response.completed_at = data.completed_at;
+                    }
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: JSON.stringify(response, null, 2),
+                            },
+                        ],
+                    };
+                }
+                catch (error) {
+                    if (error.message.includes("404")) {
+                        return {
+                            content: [{
+                                    type: "text",
+                                    text: JSON.stringify({ success: false, error: "Task not found" }, null, 2)
+                                }]
+                        };
+                    }
+                    throw error;
+                }
+            }
+            case "approve_task": {
+                const { task_id, rating, comment } = args;
+                // 1. Get task to verify status
+                const task = await apiCall(`/tasks/${task_id}`, "GET");
+                if (task.status !== "review") {
+                    return {
+                        content: [{
+                                type: "text",
+                                text: JSON.stringify({ success: false, error: `Task is not in review status (current: ${task.status})` }, null, 2)
+                            }]
+                    };
+                }
+                // 2. Compelete task
+                await apiCall(`/tasks/${task_id}/complete`, "POST");
+                // 3. Create Review
+                await apiCall("/reviews", "POST", {
+                    task_id,
+                    reviewer_type: "ai_agent",
+                    rating,
+                    comment
+                });
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                success: true,
+                                message: "Task approved and worker credited!",
+                                task_id,
+                                amount_paid: task.price,
+                                rating,
+                            }, null, 2),
+                        },
+                    ],
+                };
+            }
+            case "list_my_tasks": {
+                const { ai_agent_name, status, limit = 20 } = args;
+                // Build query params
+                const params = new URLSearchParams();
+                if (status)
+                    params.append("status", status);
+                if (ai_agent_name)
+                    params.append("ai_agent_id", ai_agent_name);
+                params.append("limit", limit.toString());
+                const response = await apiCall(`/tasks?${params.toString()}`, "GET");
+                // Response structure from API is { tasks: [], count: n }
+                const tasks = response.tasks.map((t) => ({
+                    task_id: t.id,
+                    title: t.title,
+                    status: t.status,
+                    price: t.price,
+                    created_at: t.created_at,
+                    worker_name: t.profiles ? `${t.profiles.first_name} ${t.profiles.last_name}`.trim() : undefined
+                }));
+                return {
+                    content: [{
+                            type: "text",
+                            text: JSON.stringify({
+                                success: true,
+                                count: tasks.length,
+                                tasks
+                            }, null, 2)
+                        }]
+                };
+            }
+            default:
+                throw new Error(`Unknown tool: ${name}`);
+        }
+    }
+    catch (error) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({ success: false, error: error.message }, null, 2),
+                },
+            ],
+            isError: true,
+        };
+    }
+});
+// Run Server
+async function main() {
+    const transport = new stdio_js_1.StdioServerTransport();
+    await server.connect(transport);
+    console.error("Humanod MCP Server running on stdio");
+}
+main().catch((error) => {
+    console.error("Server error:", error);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,38 @@
+{
+    "name": "humanod-mcp",
+    "version": "1.0.0",
+    "description": "Humanod MCP Server - Hire humans from AI agents",
+    "main": "build/index.js",
+    "bin": {
+        "humanod-mcp": "build/index.js"
+    },
+    "files": [
+        "build",
+        "README.md"
+    ],
+    "scripts": {
+        "build": "tsc && chmod +x build/index.js",
+        "prepublishOnly": "npm run build",
+        "start": "node build/index.js",
+        "dev": "ts-node src/index.ts",
+        "watch": "tsc --watch"
+    },
+    "keywords": [
+        "mcp",
+        "humanod",
+        "ai",
+        "agent"
+    ],
+    "author": "Humanod",
+    "license": "MIT",
+    "devDependencies": {
+        "@modelcontextprotocol/sdk": "^1.26.0",
+        "@types/node": "^20.19.33",
+        "axios": "^1.13.5",
+        "dotenv": "^17.2.4",
+        "ts-node": "^10.9.2",
+        "typescript": "^5.9.3",
+        "zod": "^4.3.6"
+    },
+    "type": "commonjs"
+}