humanping-mcp 0.1.0

package/README.md

@@ -0,0 +1,225 @@
+# humanping-mcp
+
+MCP (Model Context Protocol) server for [HumanPing](https://humanping.io) — when your AI needs a human, just ping one.
+
+Gives AI agents the ability to delegate tasks to real humans: verify facts in the physical world, make phone calls, get gut feelings, send field missions, and more.
+
+## Install
+
+```bash
+npx humanping-mcp
+```
+
+Or install globally:
+
+```bash
+npm install -g humanping-mcp
+```
+
+## Configuration
+
+### Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "humanping": {
+      "command": "npx",
+      "args": ["-y", "humanping-mcp"],
+      "env": {
+        "HUMANPING_API_KEY": "hp_live_..."
+      }
+    }
+  }
+}
+```
+
+### Cursor
+
+Add to `.cursor/mcp.json` in your project:
+
+```json
+{
+  "mcpServers": {
+    "humanping": {
+      "command": "npx",
+      "args": ["-y", "humanping-mcp"],
+      "env": {
+        "HUMANPING_API_KEY": "hp_live_..."
+      }
+    }
+  }
+}
+```
+
+### OpenClaw / Clawdbot
+
+Add to your MCP config:
+
+```json
+{
+  "mcpServers": {
+    "humanping": {
+      "command": "npx",
+      "args": ["-y", "humanping-mcp"],
+      "env": {
+        "HUMANPING_API_KEY": "hp_live_..."
+      }
+    }
+  }
+}
+```
+
+### Windsurf
+
+Add to `~/.codeium/windsurf/mcp_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "humanping": {
+      "command": "npx",
+      "args": ["-y", "humanping-mcp"],
+      "env": {
+        "HUMANPING_API_KEY": "hp_live_..."
+      }
+    }
+  }
+}
+```
+
+## Environment Variables
+
+| Variable | Required | Description |
+|---|---|---|
+| `HUMANPING_API_KEY` | Yes | Your API key (get one at humanping.io) |
+| `HUMANPING_BASE_URL` | No | API base URL (default: `https://api.humanping.io/api/v1`) |
+
+## Tools
+
+### humanping_verify
+
+Ask a real human to verify something in the physical world.
+
+**When to use:** You need ground-truth confirmation that can't be determined from data alone.
+
+**Examples:** "Is this restaurant still open?", "Does this building have wheelchair access?", "Is there actually a park at this address?"
+
+| Param | Type | Required | Default | Description |
+|---|---|---|---|---|
+| question | string | yes | - | What to verify |
+| location | string | no | - | Physical location |
+| budget | number | no | 5.00 | Budget in dollars |
+| proof | string | no | "photo" | Proof type: photo, video, text, audio |
+
+### humanping_gut_check
+
+Get a real human's gut feeling or intuition about something.
+
+**When to use:** Subjective judgments that AI can't reliably make.
+
+**Examples:** "Does this logo feel trustworthy?", "Is this email tone too aggressive?", "Would you click this ad?"
+
+| Param | Type | Required | Default | Description |
+|---|---|---|---|---|
+| content | string | yes | - | Content to evaluate |
+| question | string | no | - | Specific question |
+| scale | string | no | "1-10" | Rating scale |
+| budget | number | no | 2.00 | Budget in dollars |
+
+### humanping_call
+
+Have a real human make a phone call on your behalf.
+
+**When to use:** Calling businesses, confirming reservations, checking availability.
+
+| Param | Type | Required | Default | Description |
+|---|---|---|---|---|
+| number | string | yes | - | Phone number (with country code) |
+| script | string | yes | - | Instructions for the caller |
+| budget | number | no | 10.00 | Budget in dollars |
+
+### humanping_field
+
+Send a human on a real-world field mission.
+
+**When to use:** Tasks requiring physical presence at a location.
+
+**Examples:** "Check if this apartment matches its listing", "Photograph this storefront", "Count how many people are in line"
+
+| Param | Type | Required | Default | Description |
+|---|---|---|---|---|
+| mission | string | yes | - | What to do on-site |
+| location | string | yes | - | Where to go |
+| budget | number | no | 15.00 | Budget in dollars |
+
+### humanping_escalate
+
+Escalate to a real human with empathy and emotional intelligence.
+
+**When to use:** Situations where AI responses feel inadequate — frustrated customers, bad news, emotional support.
+
+| Param | Type | Required | Default | Description |
+|---|---|---|---|---|
+| context | string | yes | - | Full situation context |
+| contact | string | yes | - | How to reach the person |
+| budget | number | no | 10.00 | Budget in dollars |
+
+### humanping_vibe
+
+Get a human vibe check.
+
+**When to use:** Assessing mood, tone, energy, or general feel of something.
+
+**Examples:** "What's the vibe of this neighborhood?", "How does this website feel?", "Rate the energy of this playlist"
+
+| Param | Type | Required | Default | Description |
+|---|---|---|---|---|
+| content | string | yes | - | What to vibe-check |
+| question | string | no | - | Specific question |
+| budget | number | no | 3.00 | Budget in dollars |
+
+### humanping_task
+
+Create a custom task for a human (catch-all).
+
+**When to use:** When no specialized tool fits. Research, writing, data entry, creative work, anything.
+
+| Param | Type | Required | Default | Description |
+|---|---|---|---|---|
+| description | string | yes | - | What to do |
+| type | string | no | "custom" | Task category |
+| budget | number | yes | - | Budget in dollars |
+| deadline | string | no | - | Deadline (ISO 8601 or relative) |
+| proof | string | no | - | Proof type required |
+| location | string | no | - | Location if relevant |
+
+### humanping_status
+
+Check the status of a task.
+
+| Param | Type | Required | Description |
+|---|---|---|---|
+| task_id | string | yes | Task ID (e.g. task_abc123def456) |
+
+### humanping_balance
+
+Check your wallet balance. No parameters.
+
+### humanping_fund
+
+Add funds to your wallet. Returns a Stripe checkout URL.
+
+| Param | Type | Required | Description |
+|---|---|---|---|
+| amount | number | yes | Amount in dollars |
+
+## Get an API Key
+
+Visit [humanping.io](https://humanping.io) to register your agent and get an API key.
+
+## License
+
+MIT

package/index.js

@@ -0,0 +1,283 @@
+#!/usr/bin/env node
+
+const { McpServer } = require("@modelcontextprotocol/sdk/server/mcp.js");
+const { StdioServerTransport } = require("@modelcontextprotocol/sdk/server/stdio.js");
+const { z } = require("zod");
+
+const API_KEY = process.env.HUMANPING_API_KEY;
+const BASE_URL = (process.env.HUMANPING_BASE_URL || "https://api.humanping.io/api/v1").replace(/\/$/, "");
+
+if (!API_KEY) {
+  console.error("HUMANPING_API_KEY environment variable is required.");
+  process.exit(1);
+}
+
+// --- HTTP helper ---
+
+async function apiRequest(method, path, body) {
+  const url = `${BASE_URL}${path}`;
+  const headers = {
+    "x-api-key": API_KEY,
+    "Content-Type": "application/json",
+  };
+
+  const opts = { method, headers };
+  if (body) {
+    opts.body = JSON.stringify(body);
+  }
+
+  const res = await fetch(url, opts);
+  const data = await res.json().catch(() => null);
+
+  if (!res.ok) {
+    const msg = data?.error || data?.message || `HTTP ${res.status}`;
+    throw new Error(msg);
+  }
+  return data;
+}
+
+function textResult(data) {
+  return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+}
+
+function errorResult(err) {
+  return {
+    isError: true,
+    content: [{ type: "text", text: `Error: ${err.message || err}` }],
+  };
+}
+
+// --- Server setup ---
+
+const server = new McpServer({
+  name: "humanping",
+  version: "0.1.0",
+});
+
+// --- Tool definitions ---
+
+server.tool(
+  "humanping_verify",
+  "Ask a real human to verify something in the physical world. Use this when you need ground-truth confirmation that can't be determined from data alone - e.g. 'Is this restaurant still open?', 'Does this address exist?', 'Is there a line outside this store?'. The human will go check and provide proof.",
+  {
+    question: z.string().describe("What to verify. Be specific about what you need confirmed."),
+    location: z.string().optional().describe("Physical location relevant to the verification."),
+    budget: z.number().default(5.0).describe("Maximum budget in dollars for this task."),
+    proof: z.string().default("photo").describe("Type of proof required: 'photo', 'video', 'text', or 'audio'."),
+  },
+  async ({ question, location, budget, proof }) => {
+    try {
+      const data = await apiRequest("POST", "/verify", {
+        question,
+        location,
+        budget_cents: Math.round(budget * 100),
+        proof,
+      });
+      return textResult(data);
+    } catch (err) {
+      return errorResult(err);
+    }
+  }
+);
+
+server.tool(
+  "humanping_gut_check",
+  "Get a real human's gut feeling or intuition about something. Useful for subjective judgments that AI can't reliably make - e.g. 'Does this logo feel trustworthy?', 'Is this email tone appropriate?', 'Would you click on this ad?'. Multiple humans respond for consensus.",
+  {
+    content: z.string().describe("The content to evaluate. Can be text, a description, or a URL to review."),
+    question: z.string().optional().describe("Specific question to answer about the content. If omitted, humans give a general gut reaction."),
+    scale: z.string().default("1-10").describe("Rating scale for the response (e.g. '1-10', 'yes/no', '1-5')."),
+    budget: z.number().default(2.0).describe("Maximum budget in dollars for this task."),
+  },
+  async ({ content, question, scale, budget }) => {
+    try {
+      const data = await apiRequest("POST", "/gut-check", {
+        content,
+        question,
+        scale,
+        budget_cents: Math.round(budget * 100),
+      });
+      return textResult(data);
+    } catch (err) {
+      return errorResult(err);
+    }
+  }
+);
+
+server.tool(
+  "humanping_call",
+  "Have a real human make a phone call on your behalf. Use when you need to call a business, confirm a reservation, ask about availability, or handle any phone-based task. The human follows your script and reports back.",
+  {
+    number: z.string().describe("Phone number to call (include country code, e.g. +1-555-123-4567)."),
+    script: z.string().describe("Script or instructions for the caller. Be clear about what to say, what to ask, and what information to collect."),
+    budget: z.number().default(10.0).describe("Maximum budget in dollars for this task."),
+  },
+  async ({ number, script, budget }) => {
+    try {
+      const data = await apiRequest("POST", "/call", {
+        number,
+        script,
+        budget_cents: Math.round(budget * 100),
+      });
+      return textResult(data);
+    } catch (err) {
+      return errorResult(err);
+    }
+  }
+);
+
+server.tool(
+  "humanping_field",
+  "Send a human on a real-world field mission. Use for tasks that require physical presence - e.g. 'Check if this apartment is as described', 'Take photos of this storefront', 'Visit this address and report what you see'. The human goes to the location and reports back with proof.",
+  {
+    mission: z.string().describe("Detailed description of the field mission. What should the human do, observe, or collect?"),
+    location: z.string().describe("The physical location where the mission takes place. Be as specific as possible."),
+    budget: z.number().default(15.0).describe("Maximum budget in dollars for this task."),
+  },
+  async ({ mission, location, budget }) => {
+    try {
+      const data = await apiRequest("POST", "/field", {
+        description: mission,
+        location,
+        budget_cents: Math.round(budget * 100),
+      });
+      return textResult(data);
+    } catch (err) {
+      return errorResult(err);
+    }
+  }
+);
+
+server.tool(
+  "humanping_escalate",
+  "Escalate a situation to a real human with empathy and emotional intelligence. Use when a conversation needs a human touch - e.g. delivering bad news, handling a frustrated customer, or any situation where AI responses feel inadequate. A human takes over the interaction.",
+  {
+    context: z.string().describe("Full context of the situation. Include conversation history and why escalation is needed."),
+    contact: z.string().describe("How to reach the person who needs help (email, phone, chat link, etc)."),
+    budget: z.number().default(10.0).describe("Maximum budget in dollars for this task."),
+  },
+  async ({ context, contact, budget }) => {
+    try {
+      const data = await apiRequest("POST", "/escalate", {
+        context,
+        contact,
+        budget_cents: Math.round(budget * 100),
+      });
+      return textResult(data);
+    } catch (err) {
+      return errorResult(err);
+    }
+  }
+);
+
+server.tool(
+  "humanping_vibe",
+  "Get a human vibe check on something. Use when you need a human to assess the mood, tone, or general feel of content or a situation - e.g. 'What's the vibe of this neighborhood?', 'How does this website feel?', 'What's the energy at this event?'. Returns subjective human impressions.",
+  {
+    content: z.string().describe("The content or situation to vibe-check. Can be text, a URL, a place name, or a description."),
+    question: z.string().optional().describe("Specific question about the vibe. If omitted, the human gives their general impression."),
+    budget: z.number().default(3.0).describe("Maximum budget in dollars for this task."),
+  },
+  async ({ content, question, budget }) => {
+    try {
+      const data = await apiRequest("POST", "/vibe", {
+        content,
+        question,
+        budget_cents: Math.round(budget * 100),
+      });
+      return textResult(data);
+    } catch (err) {
+      return errorResult(err);
+    }
+  }
+);
+
+server.tool(
+  "humanping_task",
+  "Create a custom task for a human. Use this as a catch-all when none of the specialized tools (verify, call, field, etc.) fit your needs. You can request anything a human can do - research, writing, data entry, creative work, and more.",
+  {
+    description: z.string().describe("Clear, detailed description of what the human should do."),
+    type: z.string().default("custom").describe("Task category: 'custom', 'research', 'creative', 'data_entry', or any descriptive label."),
+    budget: z.number().describe("Budget in dollars for this task. Required."),
+    deadline: z.string().optional().describe("Deadline for completion (ISO 8601 or relative like '2h', '1d')."),
+    proof: z.string().optional().describe("Type of proof required: 'photo', 'text', 'video', 'audio', 'screenshot'."),
+    location: z.string().optional().describe("Physical location if relevant to the task."),
+  },
+  async ({ description, type, budget, deadline, proof, location }) => {
+    try {
+      const body = {
+        description,
+        type,
+        budget_cents: Math.round(budget * 100),
+      };
+      if (deadline) body.deadline = deadline;
+      if (proof) body.proof = proof;
+      if (location) body.location = location;
+
+      const data = await apiRequest("POST", "/tasks", body);
+      return textResult(data);
+    } catch (err) {
+      return errorResult(err);
+    }
+  }
+);
+
+server.tool(
+  "humanping_status",
+  "Check the status of a previously created HumanPing task. Returns the current state, any results or proof submitted, and timeline information. Use the task_id returned when you created the task.",
+  {
+    task_id: z.string().describe("The task ID to check (e.g. 'task_abc123def456')."),
+  },
+  async ({ task_id }) => {
+    try {
+      const data = await apiRequest("GET", `/tasks/${task_id}`);
+      return textResult(data);
+    } catch (err) {
+      return errorResult(err);
+    }
+  }
+);
+
+server.tool(
+  "humanping_balance",
+  "Check your HumanPing wallet balance. Returns current balance in dollars. Use this before creating tasks to make sure you have sufficient funds.",
+  {},
+  async () => {
+    try {
+      const data = await apiRequest("GET", "/wallet");
+      return textResult(data);
+    } catch (err) {
+      return errorResult(err);
+    }
+  }
+);
+
+server.tool(
+  "humanping_fund",
+  "Add funds to your HumanPing wallet. Returns a Stripe checkout URL where the user can complete the payment. Present this URL to the user so they can add funds.",
+  {
+    amount: z.number().describe("Amount to add in dollars (e.g. 10 for $10.00)."),
+  },
+  async ({ amount }) => {
+    try {
+      const data = await apiRequest("POST", "/wallet/deposit", {
+        amount_cents: Math.round(amount * 100),
+      });
+      return textResult(data);
+    } catch (err) {
+      return errorResult(err);
+    }
+  }
+);
+
+// --- Start ---
+
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+
+main().catch((err) => {
+  console.error("Fatal:", err);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "humanping-mcp",
+  "version": "0.1.0",
+  "description": "MCP server for HumanPing — when your AI needs a human, just ping one.",
+  "main": "index.js",
+  "bin": {
+    "humanping-mcp": "./index.js"
+  },
+  "scripts": {
+    "start": "node index.js"
+  },
+  "keywords": [
+    "mcp",
+    "humanping",
+    "human-in-the-loop",
+    "ai-agents",
+    "model-context-protocol"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}