@humanops/mcp-server 0.2.0 → 0.2.1

package/README.md

@@ -0,0 +1,146 @@
+# @humanops/mcp-server
+
+MCP server for AI agents to dispatch real-world tasks to verified human operators.
+
+HumanOps bridges the gap between AI capabilities and physical-world actions. When your agent needs something done in the real world — verifying a business address, filling out a form, solving a CAPTCHA, procuring an API key — it dispatches a task to a verified human operator through this MCP server.
+
+## Installation
+
+```json
+{
+  "mcpServers": {
+    "humanops": {
+      "command": "npx",
+      "args": ["@humanops/mcp-server"],
+      "env": {
+        "HUMANOPS_API_KEY": "your-api-key"
+      }
+    }
+  }
+}
+```
+
+## Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `HUMANOPS_API_KEY` | Yes | Your HumanOps API key |
+| `HUMANOPS_API_URL` | No | API base URL (default: `https://api.humanops.io`) |
+| `HUMANOPS_SANDBOX` | No | Set to `true` for sandbox mode |
+
+## Available Tools
+
+### Physical Tasks
+
+| Tool | Description |
+|------|-------------|
+| `search_operators` | Find available operators near a location |
+| `post_task` | Create a physical task (verification, photo, delivery, inspection) |
+
+### Digital Tasks (Tier 1)
+
+| Tool | Description |
+|------|-------------|
+| `dispatch_digital_task` | Create a remote digital task |
+| `list_digital_categories` | List available categories with pricing |
+
+Categories: `CAPTCHA_SOLVING`, `FORM_FILLING`, `BROWSER_INTERACTION`, `CONTENT_REVIEW`, `DATA_VALIDATION`
+
+### Credential Tasks (Tier 2, E2EE)
+
+| Tool | Description |
+|------|-------------|
+| `dispatch_credential_task` | Create an encrypted credential delivery task |
+| `retrieve_credential` | Decrypt and retrieve delivered credentials |
+
+Categories: `ACCOUNT_CREATION`, `API_KEY_PROCUREMENT`, `PHONE_VERIFICATION`, `SUBSCRIPTION_SETUP`
+
+Credential tasks use end-to-end encryption (P-256 ECDH + AES-256-GCM). The server never sees plaintext credentials.
+
+### Task Management
+
+| Tool | Description |
+|------|-------------|
+| `get_task_result` | Get task status, proof, and verification result |
+| `check_verification_status` | Check AI Guardian verification status |
+| `cancel_task` | Cancel a pending/accepted task (refunds escrowed funds) |
+| `list_tasks` | List your tasks with optional status filter |
+
+### Payments (USDC)
+
+| Tool | Description |
+|------|-------------|
+| `get_deposit_address` | Get your USDC deposit address |
+| `fund_account` | Verify a USDC deposit (Base, Polygon, Ethereum, Arbitrum) |
+| `get_balance` | Check deposit and escrow balances |
+| `request_payout` | Request operator payout |
+
+## Example Usage
+
+### Dispatch a physical verification task
+
+```
+post_task({
+  title: "Verify business is open",
+  description: "Visit 123 Main St and confirm the restaurant is operating",
+  location: { lat: 40.7128, lng: -74.0060, address: "123 Main St, New York, NY" },
+  reward_usd: 15,
+  deadline: "2026-02-08T18:00:00Z",
+  proof_requirements: ["photo of storefront", "photo of business hours sign"],
+  task_type: "VERIFICATION"
+})
+```
+
+### Dispatch a digital task
+
+```
+dispatch_digital_task({
+  title: "Fill out vendor registration form",
+  description: "Complete the vendor registration at example.com/register",
+  digital_category: "FORM_FILLING",
+  reward_usd: 12,
+  deadline: "2026-02-08T12:00:00Z",
+  proof_requirements: ["screenshot of confirmation page"],
+  digital_instructions: "1. Go to example.com/register\n2. Fill in company details\n3. Submit and screenshot confirmation"
+})
+```
+
+### Dispatch a credential task (E2EE)
+
+```
+dispatch_credential_task({
+  title: "Create API account on DataService",
+  description: "Sign up for a free account and retrieve the API key",
+  digital_category: "API_KEY_PROCUREMENT",
+  reward_usd: 20,
+  deadline: "2026-02-08T12:00:00Z",
+  proof_requirements: ["screenshot of account dashboard"],
+  digital_instructions: "1. Go to dataservice.io/signup\n2. Create account\n3. Navigate to API keys\n4. Generate and submit the key"
+})
+// Returns { task_id, private_key } — save the private_key!
+
+// Later, retrieve the credential:
+retrieve_credential({ task_id: "...", private_key: "..." })
+// Returns { credential: "sk-abc123..." }
+```
+
+## Task Lifecycle
+
+1. **PENDING** — Task created, funds escrowed
+2. **ACCEPTED** — Operator picked up the task
+3. **SUBMITTED** — Operator submitted proof
+4. **VERIFIED** / **REJECTED** — AI Guardian reviewed the proof
+5. **COMPLETED** — Task finished, operator paid
+
+## Security
+
+- All inputs validated with Zod schemas
+- SSRF protection on callback URLs
+- API key sent only to `*.humanops.io` (configurable)
+- Redirects blocked to prevent key exfiltration
+- Credential tasks use client-side E2EE (server never sees plaintext)
+- Single-read credential retrieval (cleared after first read)
+
+## License
+
+MIT

package/dist/index.js

@@ -521,7 +521,7 @@ const ALL_TASK_TYPES = [
 ];
 const server = new Server({
     name: "humanops",
-    version: "0.2.0",
+    version: "0.2.1",
 }, {
     capabilities: { tools: {} },
 });

package/package.json

@@ -1,14 +1,14 @@
 {
   "name": "@humanops/mcp-server",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "mcpName": "io.github.thepianistdirector/humanops",
   "description": "MCP server for AI agents to dispatch real-world tasks to verified human operators via HumanOps",
   "type": "module",
   "main": "./dist/index.js",
   "bin": {
-    "humanops-mcp": "./dist/index.js"
+    "@humanops/mcp-server": "dist/index.js"
   },
-  "files": ["dist/*.js", "dist/*.d.ts"],
+  "files": ["dist/*.js", "dist/*.d.ts", "README.md"],
   "scripts": {
     "start": "node dist/index.js",
     "dev": "tsx watch src/index.ts",