ai2human-mcp 0.1.0__tar.gz

ai2human_mcp-0.1.0/.gitignore

@@ -0,0 +1,23 @@
+# macOS
+.DS_Store
+
+# Node
+node_modules/
+
+# Next.js
+.next/
+out/
+
+# Logs
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+
+# Env
+.env*
+
+# Local MVP data and generated campaign artifacts.
+data/*
+!data/db.seed.json
+.vercel

ai2human_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,75 @@
+Metadata-Version: 2.4
+Name: ai2human-mcp
+Version: 0.1.0
+Summary: AI2Human MCP server — Claude can dispatch human-execution tasks with proof verification.
+Author: AI2Human
+License: MIT
+Keywords: agent,ai2human,claude,human-in-the-loop,mcp
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Requires-Dist: fastmcp<4,>=3.0
+Requires-Dist: httpx<1,>=0.27
+Description-Content-Type: text/markdown
+
+# AI2Human MCP Server
+
+Claude can dispatch human-execution tasks with proof verification.
+
+When your Claude agent hits a step it can't complete alone — local verification, physical checks, identity actions, compliance reviews — AI2Human dispatches it to a human operator with cryptographic proof verification.
+
+## Quickstart
+
+```bash
+pip install ai2human-mcp
+```
+
+Set your API key:
+
+```bash
+export AI2HUMAN_API_KEY="your-key"
+```
+
+Run:
+
+```bash
+ai2human-mcp
+```
+
+## Claude Desktop Config
+
+```json
+{
+  "mcpServers": {
+    "ai2human": {
+      "command": "uvx",
+      "args": ["ai2human-mcp"],
+      "env": {
+        "AI2HUMAN_API_KEY": "YOUR_KEY"
+      }
+    }
+  }
+}
+```
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `ai2human_list_categories` | List supported task categories and proof types |
+| `ai2human_create_task` | Dispatch a human-execution task |
+| `ai2human_check_task` | Check task status, verification, and settlement |
+| `ai2human_get_proof` | Retrieve evidence bundle and settlement receipt |
+
+## Environment
+
+| Variable | Required | Default |
+|----------|----------|---------|
+| `AI2HUMAN_API_KEY` | Yes | — |
+| `AI2HUMAN_AGENT_KEY` | No | Fallback for API key |
+| `AI2HUMAN_BASE_URL` | No | `https://ai2human.io` |

ai2human_mcp-0.1.0/README.md

@@ -0,0 +1,56 @@
+# AI2Human MCP Server
+
+Claude can dispatch human-execution tasks with proof verification.
+
+When your Claude agent hits a step it can't complete alone — local verification, physical checks, identity actions, compliance reviews — AI2Human dispatches it to a human operator with cryptographic proof verification.
+
+## Quickstart
+
+```bash
+pip install ai2human-mcp
+```
+
+Set your API key:
+
+```bash
+export AI2HUMAN_API_KEY="your-key"
+```
+
+Run:
+
+```bash
+ai2human-mcp
+```
+
+## Claude Desktop Config
+
+```json
+{
+  "mcpServers": {
+    "ai2human": {
+      "command": "uvx",
+      "args": ["ai2human-mcp"],
+      "env": {
+        "AI2HUMAN_API_KEY": "YOUR_KEY"
+      }
+    }
+  }
+}
+```
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `ai2human_list_categories` | List supported task categories and proof types |
+| `ai2human_create_task` | Dispatch a human-execution task |
+| `ai2human_check_task` | Check task status, verification, and settlement |
+| `ai2human_get_proof` | Retrieve evidence bundle and settlement receipt |
+
+## Environment
+
+| Variable | Required | Default |
+|----------|----------|---------|
+| `AI2HUMAN_API_KEY` | Yes | — |
+| `AI2HUMAN_AGENT_KEY` | No | Fallback for API key |
+| `AI2HUMAN_BASE_URL` | No | `https://ai2human.io` |

ai2human_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "ai2human-mcp"
+version = "0.1.0"
+description = "AI2Human MCP server — Claude can dispatch human-execution tasks with proof verification."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.10"
+authors = [{ name = "AI2Human" }]
+keywords = ["ai2human", "mcp", "claude", "agent", "human-in-the-loop"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+dependencies = [
+    "fastmcp>=3.0,<4",
+    "httpx>=0.27,<1",
+]
+
+[project.scripts]
+ai2human-mcp = "ai2human_mcp.server:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/ai2human_mcp"]

ai2human_mcp-0.1.0/src/ai2human_mcp/__init__.py

@@ -0,0 +1,3 @@
+from .client import AI2HumanAPIError, AI2HumanClient
+
+__all__ = ["AI2HumanAPIError", "AI2HumanClient"]

ai2human_mcp-0.1.0/src/ai2human_mcp/client.py

@@ -0,0 +1,104 @@
+from __future__ import annotations
+
+import os
+from typing import Any
+
+import httpx
+
+
+class AI2HumanAPIError(RuntimeError):
+    def __init__(self, message: str, status_code: int, details: Any) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.details = details
+
+
+class AI2HumanClient:
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        transport: httpx.BaseTransport | None = None,
+        async_transport: httpx.AsyncBaseTransport | None = None,
+    ) -> None:
+        self.api_key = api_key or os.getenv("AI2HUMAN_API_KEY") or os.getenv("AI2HUMAN_AGENT_KEY") or ""
+        self.base_url = (base_url or os.getenv("AI2HUMAN_BASE_URL") or "https://ai2human.io").rstrip("/")
+        self.transport = transport
+        self.async_transport = async_transport
+
+    def _headers(self) -> dict[str, str]:
+        if not self.api_key:
+            raise AI2HumanAPIError(
+                "AI2HUMAN_API_KEY is required. Create one at https://ai2human.io/developers/api-keys.",
+                401,
+                {"code": "AGENT_API_KEY_REQUIRED"},
+            )
+        return {"Accept": "application/json", "x-agent-api-key": self.api_key}
+
+    @staticmethod
+    def _read(response: httpx.Response) -> dict[str, Any]:
+        try:
+            payload = response.json()
+        except ValueError:
+            payload = {"error": f"HTTP {response.status_code}"}
+        if response.is_error:
+            raise AI2HumanAPIError(str(payload.get("error") or response.reason_phrase), response.status_code, payload)
+        return payload
+
+    def _request(self, method: str, path: str, **kwargs: Any) -> dict[str, Any]:
+        with httpx.Client(base_url=self.base_url, headers=self._headers(), transport=self.transport, timeout=30) as client:
+            return self._read(client.request(method, path, **kwargs))
+
+    async def _arequest(self, method: str, path: str, **kwargs: Any) -> dict[str, Any]:
+        async with httpx.AsyncClient(
+            base_url=self.base_url,
+            headers=self._headers(),
+            transport=self.async_transport,
+            timeout=30,
+        ) as client:
+            return self._read(await client.request(method, path, **kwargs))
+
+    def create_task(self, payload: dict[str, Any]) -> dict[str, Any]:
+        return self._request("POST", "/api/agent/tasks", json=payload)
+
+    async def acreate_task(self, payload: dict[str, Any]) -> dict[str, Any]:
+        return await self._arequest("POST", "/api/agent/tasks", json=payload)
+
+    def check_task(self, task_id: str) -> dict[str, Any]:
+        return self._request("GET", f"/api/tasks/{task_id}")
+
+    async def acheck_task(self, task_id: str) -> dict[str, Any]:
+        return await self._arequest("GET", f"/api/tasks/{task_id}")
+
+    def get_proof(self, task_id: str) -> dict[str, Any]:
+        payload = self.check_task(task_id)
+        task = payload.get("task") or {}
+        campaign = task.get("campaign") or {}
+        return {
+            "task_id": task.get("id"),
+            "title": task.get("title"),
+            "proof_requirements": campaign.get("proofRequirements") or [],
+            "evidence": task.get("evidence") or [],
+            "verification_status": task.get("status"),
+            "payment": payload.get("payment"),
+        }
+
+    async def aget_proof(self, task_id: str) -> dict[str, Any]:
+        payload = await self.acheck_task(task_id)
+        task = payload.get("task") or {}
+        campaign = task.get("campaign") or {}
+        return {
+            "task_id": task.get("id"),
+            "title": task.get("title"),
+            "proof_requirements": campaign.get("proofRequirements") or [],
+            "evidence": task.get("evidence") or [],
+            "verification_status": task.get("status"),
+            "payment": payload.get("payment"),
+        }
+
+    def list_categories(self) -> dict[str, Any]:
+        return self._request("GET", "/api/agent/tasks/categories")
+
+    async def alist_categories(self) -> dict[str, Any]:
+        return await self._arequest("GET", "/api/agent/tasks/categories")

ai2human_mcp-0.1.0/src/ai2human_mcp/server.py

@@ -0,0 +1,98 @@
+"""AI2Human MCP server — expose human-execution tools to Claude and other MCP clients."""
+
+from __future__ import annotations
+
+import json
+from typing import Literal
+
+from mcp.server.fastmcp import FastMCP
+
+from .client import AI2HumanClient
+
+mcp = FastMCP("ai2human")
+client = AI2HumanClient()
+
+TaskCategory = Literal[
+    "local_verification", "identity_action", "physical_task",
+    "digital_task", "compliance_check", "errand",
+]
+ProofType = Literal[
+    "screenshot", "photo", "url", "timestamp", "receipt", "signature", "notes",
+]
+
+
+def _json(v: object) -> str:
+    return json.dumps(v, ensure_ascii=False, indent=2)
+
+
+@mcp.tool(
+    name="ai2human_create_task",
+    description=(
+        "Dispatch a workflow step that software cannot complete alone to a human operator. "
+        "Use for local verification, physical checks, identity-bound actions, document review, "
+        "compliance checks, or errands. Payment remains gated by proof verification."
+    ),
+)
+async def ai2human_create_task(
+    title: str,
+    description: str,
+    category: TaskCategory,  # type: ignore[valid-type]
+    proof_requirements: list[ProofType],  # type: ignore[valid-type]
+    reward_usdc: float,
+    deadline_hours: float,
+    location: str | None = None,
+    agent_name: str | None = None,
+    acceptance_criteria: str | None = None,
+) -> str:
+    payload: dict[str, object] = {
+        "title": title,
+        "description": description,
+        "category": category,
+        "proof_requirements": proof_requirements,
+        "reward_usdc": reward_usdc,
+        "deadline_hours": deadline_hours,
+    }
+    if location is not None:
+        payload["location"] = location
+    if agent_name is not None:
+        payload["agent_name"] = agent_name
+    if acceptance_criteria is not None:
+        payload["acceptance_criteria"] = acceptance_criteria
+
+    result = await client.acreate_task(payload)
+    return _json(result)
+
+
+@mcp.tool(
+    name="ai2human_check_task",
+    description="Check human execution, proof verification, and settlement state for a dispatched task.",
+)
+async def ai2human_check_task(task_id: str) -> str:
+    result = await client.acheck_task(task_id)
+    return _json(result)
+
+
+@mcp.tool(
+    name="ai2human_get_proof",
+    description="Retrieve the structured evidence bundle and recorded settlement receipt for a dispatched task.",
+)
+async def ai2human_get_proof(task_id: str) -> str:
+    result = await client.aget_proof(task_id)
+    return _json(result)
+
+
+@mcp.tool(
+    name="ai2human_list_categories",
+    description="List supported reality-bound task categories and proof types before dispatching human work.",
+)
+async def ai2human_list_categories() -> str:
+    result = await client.alist_categories()
+    return _json(result)
+
+
+def main() -> None:
+    mcp.run(transport="stdio")
+
+
+if __name__ == "__main__":
+    main()