humanbottasks 0.1.0__tar.gz

humanbottasks-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+.venv/
+__pycache__/
+dist/
+tasks.db
+*.log
+uv.lock

humanbottasks-0.1.0/FORUM_POSTS.md

@@ -0,0 +1,69 @@
+# Forum-/Community-Posts (fertig zum Copy-Paste)
+
+Englisch, weil die Zielgruppe (AI-Builder) englischsprachig ist.
+Posten braucht deine Accounts — die Texte sind einsatzbereit.
+
+---
+
+## Reddit r/MCP
+
+**Title:** I built humanbottasks — delegate anything your agent can't do to a real human, over MCP
+
+**Body:**
+Two tools. That's the whole API:
+
+- `request_human_task(type, description, max_price)` — verification, physical_action, subjective_judgment, ground_truth_labeling, prove_human
+- `get_task_status(task_id)` — poll for the result
+
+Install: `uvx --from git+https://github.com/humanbottasks/humanbottasks humanbottasks`
+
+Works over stdio (Claude Desktop, Cursor, Windsurf) and streamable-http (remote agents).
+
+I built this because I kept hitting the same wall: agents confidently asserting things they couldn't verify, with no clean handoff for the parts only a human can do. The existing options either want me to wire up a marketplace account or bolt on a whole SDK — I wanted the thinnest possible thing that just works.
+
+It's an MVP (SQLite queue, no payments yet — I fulfill tasks manually right now). Honest question for this sub: which task type actually matters to you? Where do your agents actually get stuck?
+
+Repo: https://github.com/humanbottasks/humanbottasks
+
+---
+
+## Reddit r/LocalLLaMA
+
+**Title:** Local agents can now call a human — humanbottasks (MCP, stdio, no cloud)
+
+**Body:**
+If you run local agents (Ollama/LM Studio + LangChain/CrewAI), here's a human-in-the-loop fallback that's just an MCP server on your own machine. No cloud account, no hosted service.
+
+- stdio (spawn it as a subprocess, same as any MCP server) + streamable-http for remote
+- Two tools: request_human_task / get_task_status
+- SQLite queue, you (or anyone) fulfill via a one-line CLI
+
+Install: `uvx --from git+https://github.com/humanbottasks/humanbottasks humanbottasks`
+
+Why this matters for local agents specifically: local models are even worse at verification and physical-world actions than frontier models, and they can't buy things or pick up a phone at all. A local agent that can delegate the "actually check this" part to a human is much more useful.
+
+Repo: https://github.com/humanbottasks/humanbottasks
+
+---
+
+## X/Twitter (Thread, 3 Posts)
+
+**Post 1:**
+Your agent can't do everything. Now it can ask a human — over MCP, one line:
+`uvx --from git+https://github.com/humanbottasks/humanbottasks humanbottasks`
+
+**Post 2:**
+Two tools: `request_human_task` and `get_task_status`. That's it. Verification, physical actions, subjective judgment, ground-truth labeling — delegate it to a real person, poll for the result. stdio + streamable-http.
+
+**Post 3:**
+Built this after watching agents confidently assert things they couldn't verify, with no clean handoff for the human parts. Open source, MIT, works with Claude Desktop / Cursor / Windsurf / local agents.
+https://github.com/humanbottasks/humanbottasks
+
+---
+
+## Discord (MCP / LangChain / n8n / Dify servers)
+
+**Kurzer Blurb:**
+> humanbottasks — human fallback for AI agents over MCP. Two tools (request_human_task / get_task_status), stdio + streamable-http, one-line install:
+> `uvx --from git+https://github.com/humanbottasks/humanbottasks humanbottasks`
+> MIT, works with Claude Desktop/Cursor/Windsurf and local agent frameworks.

humanbottasks-0.1.0/LAUNCH_POST.md

@@ -0,0 +1,33 @@
+# Show HN / Launch Post
+
+Fertig zum Einfuegen (Show HN, X, Discord, Reddit r/MCP r/LocalLLaMA).
+
+---
+
+**Show HN: humanbottasks — human fallback for AI agents over MCP**
+
+Your agent can't do everything. When it needs to verify a fact, make a phone
+call, buy or ship something, or judge whether text sounds natural, it can now
+delegate that to a real human — over MCP, one line.
+
+Two tools:
+- `request_human_task(type, description, max_price)` — submit a task
+- `get_task_status(task_id)` — poll for the result
+
+Install:
+    uvx --from git+https://github.com/humanbottasks/humanbottasks humanbottasks
+
+Works with Claude Desktop, Cursor, Windsurf (stdio) and remote agents
+(streamable-http). Task types: verification, physical_action,
+subjective_judgment, ground_truth_labeling, prove_human.
+
+Why: models are great at reasoning and bad at anything that touches the
+physical world or needs verified judgment. This is the thinnest possible
+"human in the loop" — no SDK, just MCP, the protocol agents already speak.
+
+I kept hitting the same wall: agents confidently asserting things they
+couldn't verify, with no clean way to hand off the parts only a human can do.
+So I built the handoff. Would love feedback — especially on which task types
+matter most to you.
+
+Repo: https://github.com/humanbottasks/humanbottasks

humanbottasks-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 humanbottasks
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

humanbottasks-0.1.0/PKG-INFO

@@ -0,0 +1,53 @@
+Metadata-Version: 2.5
+Name: humanbottasks
+Version: 0.1.0
+Summary: Human fallback for AI agents: delegate tasks a model can't do to a human, over MCP.
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: mcp<2
+Description-Content-Type: text/markdown
+
+# humanbottasks
+
+Gemanagter Human-Service-Layer fuer AI-Agenten. Ein AI-Agent delegiert ueber MCP
+eine Aufgabe, die er nicht selbst kann, an einen Menschen; der Mensch erledigt
+sie, der Agent ruft das Ergebnis ab.
+
+## MVP-Status
+- `server.py`   MCP-Server (Tools: request_human_task, get_task_status)
+- `store.py`    SQLite-Queue (tasks.db)
+- `fulfill.py`  CLI fuer den Menschen (Tasks ansehen/erledigen)
+- `demo.py`     End-to-End-Demo (Agent -> Task -> Mensch -> Ergebnis)
+- `test_smoke.py` Smoke-Test
+
+## Setup & Start
+    cd humanbottasks
+    unset PYTHONPATH
+    uv venv
+    uv pip install "mcp<2"
+    uv run server.py
+
+## Transporte
+    uv run server.py                                  # stdio (Claude Desktop, Cursor, lokale Frameworks)
+    uv run server.py --transport streamable-http      # HTTP-Endpoint http://127.0.0.1:8000/mcp (lokal/Remote-Agents)
+    uv run server.py --transport sse                  # Legacy-SSE http://127.0.0.1:8000/sse
+
+Host/Port via Umgebungsvariablen: HBT_HOST (default 127.0.0.1), HBT_PORT (default 8000).
+Fuer Remote-Zugriff: HBT_HOST=0.0.0.0 setzen.
+
+## Install (fuer andere Builder, 1 Zeile)
+    uvx --from git+https://github.com/humanbottasks/humanbottasks humanbottasks
+
+## Task-Typen
+verification · physical_action · subjective_judgment · ground_truth_labeling · prove_human
+
+## MCP-Clients (installiert + konfiguriert)
+- **Claude Desktop**: `C:\Users\marku\AppData\Roaming\Claude\claude_desktop_config.json`
+- **Cursor**: `C:\Users\marku\.cursor\mcp.json`
+- **Windsurf**: `C:\Users\marku\.codeium\windsurf\mcp_config.json`
+- Templates in `config/` (falls neu einrichten noetig)
+
+## Naechste Schritte (Reihenfolge)
+1. Nachfrage-Test: Server laeuft, ein echter Agent ruft request_human_task.
+2. Website/Landing fuer Agent-Builder.
+3. Payments (Stripe/Circle) erst, wenn Nachfrage da ist.

humanbottasks-0.1.0/README.md

@@ -0,0 +1,44 @@
+# humanbottasks
+
+Gemanagter Human-Service-Layer fuer AI-Agenten. Ein AI-Agent delegiert ueber MCP
+eine Aufgabe, die er nicht selbst kann, an einen Menschen; der Mensch erledigt
+sie, der Agent ruft das Ergebnis ab.
+
+## MVP-Status
+- `server.py`   MCP-Server (Tools: request_human_task, get_task_status)
+- `store.py`    SQLite-Queue (tasks.db)
+- `fulfill.py`  CLI fuer den Menschen (Tasks ansehen/erledigen)
+- `demo.py`     End-to-End-Demo (Agent -> Task -> Mensch -> Ergebnis)
+- `test_smoke.py` Smoke-Test
+
+## Setup & Start
+    cd humanbottasks
+    unset PYTHONPATH
+    uv venv
+    uv pip install "mcp<2"
+    uv run server.py
+
+## Transporte
+    uv run server.py                                  # stdio (Claude Desktop, Cursor, lokale Frameworks)
+    uv run server.py --transport streamable-http      # HTTP-Endpoint http://127.0.0.1:8000/mcp (lokal/Remote-Agents)
+    uv run server.py --transport sse                  # Legacy-SSE http://127.0.0.1:8000/sse
+
+Host/Port via Umgebungsvariablen: HBT_HOST (default 127.0.0.1), HBT_PORT (default 8000).
+Fuer Remote-Zugriff: HBT_HOST=0.0.0.0 setzen.
+
+## Install (fuer andere Builder, 1 Zeile)
+    uvx --from git+https://github.com/humanbottasks/humanbottasks humanbottasks
+
+## Task-Typen
+verification · physical_action · subjective_judgment · ground_truth_labeling · prove_human
+
+## MCP-Clients (installiert + konfiguriert)
+- **Claude Desktop**: `C:\Users\marku\AppData\Roaming\Claude\claude_desktop_config.json`
+- **Cursor**: `C:\Users\marku\.cursor\mcp.json`
+- **Windsurf**: `C:\Users\marku\.codeium\windsurf\mcp_config.json`
+- Templates in `config/` (falls neu einrichten noetig)
+
+## Naechste Schritte (Reihenfolge)
+1. Nachfrage-Test: Server laeuft, ein echter Agent ruft request_human_task.
+2. Website/Landing fuer Agent-Builder.
+3. Payments (Stripe/Circle) erst, wenn Nachfrage da ist.

humanbottasks-0.1.0/SUBMISSION.md

@@ -0,0 +1,44 @@
+# humanbottasks — Directory Submission Copy
+
+Fertige Texte fuer MCP-Registries (mcp.so, PulseMCP, glama.ai/mcp, smithery.ai, Cline Marketplace).
+Einfuegen bei Submission; Tagline/Description je nach Feld passend kuerzen.
+
+## Name
+humanbottasks
+
+## Tagline (eine Zeile)
+Human fallback for AI agents — delegate anything a model can't do to a real person, over MCP.
+
+## Description (lang)
+humanbottasks is a managed human-service layer for AI agents. When an agent hits
+something it can't or shouldn't do itself — verify a fact, make a phone call,
+buy or ship something, judge whether text sounds natural, label ground-truth
+data — it delegates the task to a human over MCP and polls for the result.
+
+Two tools: `request_human_task` (submit a task with a type, description and max
+price) and `get_task_status` (poll status and read the result).
+
+Task types: verification, physical_action, subjective_judgment,
+ground_truth_labeling, prove_human.
+
+Transports: stdio (Claude Desktop, Cursor, Windsurf, local frameworks) and
+streamable-http (remote agents).
+
+## Category / Tags
+human-in-the-loop, task-delegation, human-fallback, agent-tools, mcp
+
+## Install
+uvx --from git+https://github.com/humanbottasks/humanbottasks humanbottasks
+
+## MCP client config
+{"mcpServers":{"humanbottasks":{"command":"uvx","args":["--from","git+https://github.com/humanbottasks/humanbottasks","humanbottasks"]}}}
+
+## Use cases (fuer Directory-Description)
+- Prove a claim before the agent states it (verification)
+- Phone calls, purchases, shipments (physical_action)
+- "Does this sound natural / is this good?" (subjective_judgment)
+- Ground-truth data for fine-tuning and evals (ground_truth_labeling)
+- CAPTCHA / account / identity checks (prove_human)
+
+## Repo
+https://github.com/humanbottasks/humanbottasks

humanbottasks-0.1.0/alarm.py

@@ -0,0 +1,62 @@
+"""Task-Eingangs-Alarm: gibt NEUE offene Tasks aus; leere Ausgabe = nichts senden.
+
+Wird als no_agent-Cron-Script genutzt: stdout wird verbatim an Telegram geliefert.
+"""
+import os
+import sqlite3
+
+DB = "C:/Users/marku/humanbottasks/tasks.db"
+STATE = "C:/Users/marku/humanbottasks/data/reported_ids.txt"
+
+
+def _load():
+    if not os.path.exists(STATE):
+        return set()
+    with open(STATE, encoding="utf-8") as f:
+        return {ln.strip() for ln in f if ln.strip()}
+
+
+def _save(ids):
+    os.makedirs(os.path.dirname(STATE), exist_ok=True)
+    with open(STATE, "w", encoding="utf-8") as f:
+        for i in sorted(ids):
+            f.write(i + "\n")
+
+
+def main():
+    if not os.path.exists(DB):
+        return
+    conn = sqlite3.connect(DB)
+    conn.row_factory = sqlite3.Row
+    try:
+        rows = conn.execute(
+            "SELECT * FROM tasks WHERE status='pending' ORDER BY created_at"
+        ).fetchall()
+    except sqlite3.OperationalError:
+        return
+    finally:
+        conn.close()
+
+    if not rows:
+        return
+
+    reported = _load()
+    new = [r for r in rows if r["id"] not in reported]
+
+    # Zustand synchron halten (auch bereits bekannte pending merken)
+    _save([r["id"] for r in rows])
+
+    if not new:
+        return
+
+    lines = ["\U0001f195 Neue humanbottasks-Task(s):"]
+    for r in new:
+        lines.append(f"  {r['id']}  [{r['task_type']}]  ${r['max_price_usd']:.2f}")
+        lines.append(f"  {r['description']}")
+    lines.append("")
+    lines.append('Erledigen (im Ordner humanbottasks): python fulfill.py done <task_id> "<Ergebnis>"')
+    print("\n".join(lines))
+
+
+if __name__ == "__main__":
+    main()

humanbottasks-0.1.0/config/claude_desktop_config.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "humanbottasks": {
+      "command": "C:\\Users\\marku\\humanbottasks\\.venv\\Scripts\\python.exe",
+      "args": ["C:\\Users\\marku\\humanbottasks\\server.py"]
+    }
+  }
+}

humanbottasks-0.1.0/config/cursor_mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "humanbottasks": {
+      "command": "C:\\Users\\marku\\humanbottasks\\.venv\\Scripts\\python.exe",
+      "args": ["C:\\Users\\marku\\humanbottasks\\server.py"]
+    }
+  }
+}

humanbottasks-0.1.0/data/reported_ids.txt

@@ -0,0 +1 @@
+bad3938bf65a

humanbottasks-0.1.0/demo.py

@@ -0,0 +1,49 @@
+"""End-to-End-Demo: Agent delegiert Task -> Mensch erledigt -> Agent liest Ergebnis."""
+import asyncio, sys, os, re
+import store as q
+
+from mcp import ClientSession, StdioServerParameters
+from mcp.client.stdio import stdio_client
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+
+
+async def main():
+    params = StdioServerParameters(command=sys.executable, args=["server.py"], cwd=HERE)
+    async with stdio_client(params) as (read, write):
+        async with ClientSession(read, write) as session:
+            await session.initialize()
+            tools = await session.list_tools()
+            print("== Tools ==")
+            for t in tools.tools:
+                print(" -", t.name)
+
+            print("\n== 1) Agent delegiert eine Task ==")
+            res = await session.call_tool(
+                "request_human_task",
+                {
+                    "task_type": "subjective_judgment",
+                    "description": "Bewerte, ob dieser Satz natuerlich klingt: 'Ich habe das Auto gewaschen.'",
+                    "max_price_usd": 8.0,
+                },
+            )
+            text = res.content[0].text if res.content else str(res)
+            print(text)
+            m = re.search(r"task_id=([0-9a-f]+)", text)
+            tid = m.group(1) if m else None
+            assert tid, "keine task_id gefunden"
+
+            print("\n== 2) Status direkt nach Aufgeben ==")
+            res = await session.call_tool("get_task_status", {"task_id": tid})
+            print(res.content[0].text)
+
+            print("\n== 3) Mensch erledigt die Task ==")
+            q.complete(tid, "Der Satz klingt natuerlich und korrekt.")
+            print("Mensch hat abgeschlossen.")
+
+            print("\n== 4) Agent liest das Ergebnis ==")
+            res = await session.call_tool("get_task_status", {"task_id": tid})
+            print(res.content[0].text)
+
+
+asyncio.run(main())

humanbottasks-0.1.0/fulfill.py

@@ -0,0 +1,17 @@
+"""CLI fuer den Menschen: offene Tasks ansehen und erledigen (MVP-Fulfillment)."""
+import sys
+import store as q
+
+q.init()
+
+if len(sys.argv) >= 4 and sys.argv[1] == "done":
+    q.complete(sys.argv[2], " ".join(sys.argv[3:]))
+    print("Erledigt:", sys.argv[2])
+
+rows = q.pending()
+if not rows:
+    print("Keine offenen Tasks.")
+else:
+    for r in rows:
+        print(f"{r['id']}  [{r['task_type']}]  ${r['max_price_usd']:.2f}  {r['description'][:90]}")
+    print("\nErledigen: python fulfill.py done <task_id> <Ergebnis-Text>")

humanbottasks-0.1.0/glama.json

@@ -0,0 +1,4 @@
+{
+  "$schema": "https://glama.ai/mcp/schemas/server.json",
+  "maintainers": ["humanbottasks"]
+}

humanbottasks-0.1.0/http_demo.py

@@ -0,0 +1,33 @@
+"""HTTP-Referenz: Agent verbindet sich ueber streamable-http (fuer Remote-/lokale Agents
+auf anderen Maschinen). Vorher Server starten:
+
+    uv run server.py --transport streamable-http
+
+Dann diesen Client laufen lassen (von ueberall im Netz, wenn HBT_HOST=0.0.0.0 gesetzt):
+"""
+import asyncio
+import sys
+
+from mcp import ClientSession
+from mcp.client.streamable_http import streamablehttp_client
+
+URL = "http://127.0.0.1:8000/mcp"
+
+
+async def main():
+    async with streamablehttp_client(URL) as (read, write, _):
+        async with ClientSession(read, write) as session:
+            await session.initialize()
+            tools = await session.list_tools()
+            print("Tools:", [t.name for t in tools.tools])
+            res = await session.call_tool(
+                "request_human_task",
+                {"task_type": "verification",
+                 "description": "HTTP-Test: pruefe ob die Integration funktioniert",
+                 "max_price_usd": 5.0},
+            )
+            print(res.content[0].text)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

humanbottasks-0.1.0/index.html

@@ -0,0 +1,90 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>humanbottasks — Human fallback for AI agents</title>
+<meta name="description" content="Delegate anything your AI agent can't do — verification, physical actions, subjective judgment — to a real human over MCP.">
+<style>
+  :root { --bg:#0a0a0f; --fg:#e8e8f0; --muted:#9a9ab0; --accent:#7c5cff; --accent2:#00d4aa; --card:#14141d; --border:#26263a; }
+  * { margin:0; padding:0; box-sizing:border-box; }
+  body { background:var(--bg); color:var(--fg); font-family:-apple-system,"Segoe UI",Roboto,Helvetica,Arial,sans-serif; line-height:1.6; }
+  a { color:var(--accent2); text-decoration:none; }
+  .wrap { max-width:960px; margin:0 auto; padding:0 24px; }
+  header { padding:32px 0; border-bottom:1px solid var(--border); }
+  .logo { font-weight:800; font-size:20px; letter-spacing:-0.5px; }
+  .logo span { color:var(--accent); }
+  .hero { padding:72px 0 48px; }
+  h1 { font-size:44px; line-height:1.15; letter-spacing:-1px; font-weight:800; }
+  h1 .grad { background:linear-gradient(90deg,var(--accent),var(--accent2)); -webkit-background-clip:text; background-clip:text; color:transparent; }
+  .sub { margin-top:20px; font-size:20px; color:var(--muted); max-width:640px; }
+  .cta { margin-top:32px; display:flex; gap:12px; flex-wrap:wrap; }
+  .btn { padding:12px 24px; border-radius:8px; font-weight:600; font-size:15px; display:inline-block; }
+  .btn-primary { background:var(--accent); color:#fff; }
+  .btn-ghost { border:1px solid var(--border); color:var(--fg); }
+  .grid { display:grid; grid-template-columns:repeat(auto-fit,minmax(260px,1fr)); gap:16px; padding:48px 0; }
+  .card { background:var(--card); border:1px solid var(--border); border-radius:12px; padding:24px; }
+  .card h3 { font-size:17px; margin-bottom:8px; }
+  .card p { color:var(--muted); font-size:15px; }
+  .code { background:var(--card); border:1px solid var(--border); border-radius:12px; padding:20px 24px; font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,monospace; font-size:14px; overflow-x:auto; color:#c9d1ff; margin:24px 0; }
+  .code .c { color:var(--muted); }
+  .steps { padding:32px 0; counter-reset:step; }
+  .step { display:flex; gap:16px; align-items:flex-start; margin-bottom:24px; }
+  .step .n { background:var(--accent); color:#fff; border-radius:50%; width:32px; height:32px; display:flex; align-items:center; justify-content:center; font-weight:700; flex-shrink:0; }
+  .step h4 { margin-bottom:4px; }
+  .step p { color:var(--muted); }
+  .chips { display:flex; flex-wrap:wrap; gap:8px; padding:24px 0 48px; }
+  .chip { border:1px solid var(--border); color:var(--muted); border-radius:999px; padding:6px 14px; font-size:13px; }
+  footer { border-top:1px solid var(--border); padding:32px 0; color:var(--muted); font-size:14px; }
+  .h2 { font-size:28px; letter-spacing:-0.5px; font-weight:700; margin-top:8px; }
+</style>
+</head>
+<body>
+  <header><div class="wrap"><div class="logo">human<span>bot</span>tasks</div></div></header>
+
+  <section class="hero"><div class="wrap">
+    <h1>Your agent can't do everything.<br><span class="grad">Now it can ask a human.</span></h1>
+    <p class="sub">humanbottasks is a managed human-service layer for AI agents. Delegate verification, physical actions and subjective judgment to a real person — over MCP, one line.</p>
+    <div class="cta">
+      <a class="btn btn-primary" href="https://github.com/humanbottasks/humanbottasks">Get started</a>
+      <a class="btn btn-ghost" href="#install">View install</a>
+    </div>
+  </div></section>
+
+  <section class="wrap">
+    <div class="grid">
+      <div class="card"><h3>Delegate anything</h3><p>Verification, phone calls, purchases, data labeling, subjective judgment — whatever the model can't or shouldn't do itself.</p></div>
+      <div class="card"><h3>Standard MCP</h3><p>Works with Claude Desktop, Cursor, Windsurf and any local agent framework. stdio for local, HTTP for remote.</p></div>
+      <div class="card"><h3>You stay in control</h3><p>A real human fulfills the task; your agent polls the result. You set the max price per task.</p></div>
+    </div>
+  </section>
+
+  <section class="wrap" id="install">
+    <div class="h2">Install</div>
+    <div class="code"><span class="c"># one command</span><br>uvx --from git+https://github.com/humanbottasks/humanbottasks humanbottasks</div>
+    <div class="code"><span class="c"># MCP client config (Claude Desktop / Cursor / Windsurf)</span><br>{"mcpServers":{"humanbottasks":{"command":"uvx","args":["--from","git+https://github.com/humanbottasks/humanbottasks","humanbottasks"]}}}</div>
+  </section>
+
+  <section class="wrap">
+    <div class="h2">How it works</div>
+    <div class="steps">
+      <div class="step"><div class="n">1</div><div><h4>Agent delegates</h4><p>The agent calls request_human_task with a description and max price.</p></div></div>
+      <div class="step"><div class="n">2</div><div><h4>Human fulfills</h4><p>A real person does the task and submits the result.</p></div></div>
+      <div class="step"><div class="n">3</div><div><h4>Agent reads the result</h4><p>The agent polls get_task_status and continues with the answer.</p></div></div>
+    </div>
+  </section>
+
+  <section class="wrap">
+    <div class="h2">Task types</div>
+    <div class="chips">
+      <span class="chip">verification</span>
+      <span class="chip">physical_action</span>
+      <span class="chip">subjective_judgment</span>
+      <span class="chip">ground_truth_labeling</span>
+      <span class="chip">prove_human</span>
+    </div>
+  </section>
+
+  <footer><div class="wrap">humanbottasks — human fallback for AI agents. © 2026</div></footer>
+</body>
+</html>

humanbottasks-0.1.0/pyproject.toml

@@ -0,0 +1,18 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "humanbottasks"
+version = "0.1.0"
+description = "Human fallback for AI agents: delegate tasks a model can't do to a human, over MCP."
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = ["mcp<2"]
+
+[project.scripts]
+humanbottasks = "server:main"
+
+[tool.hatch.build.targets.wheel]
+packages = []
+force-include = { "server.py" = "server.py", "store.py" = "store.py", "fulfill.py" = "fulfill.py", "alarm.py" = "alarm.py" }

humanbottasks-0.1.0/server.json

@@ -0,0 +1,23 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.humanbottasks/humanbottasks",
+  "title": "humanbottasks",
+  "description": "Human fallback for AI agents: delegate tasks to a human over MCP.",
+  "websiteUrl": "https://humanbottasks.github.io/humanbottasks/",
+  "repository": {
+    "url": "https://github.com/humanbottasks/humanbottasks",
+    "source": "github"
+  },
+  "version": "0.1.0",
+  "packages": [
+    {
+      "registryType": "pypi",
+      "registryBaseUrl": "https://pypi.org",
+      "identifier": "humanbottasks",
+      "version": "0.1.0",
+      "transport": {
+        "type": "stdio"
+      }
+    }
+  ]
+}

humanbottasks-0.1.0/server.py

@@ -0,0 +1,83 @@
+"""humanbottasks MCP-Server: AI-Agenten delegieren Tasks an Menschen.
+
+Der Server exponiert zwei Tools ueber MCP:
+  - request_human_task: Agent stellt eine Aufgabe ein
+  - get_task_status:   Agent fragt Status/Ergebnis ab
+
+Transport (--transport): stdio (default), streamable-http, sse.
+
+Ein Mensch erledigt die Tasks ueber fulfill.py (CLI).
+"""
+import os
+from mcp.server.fastmcp import FastMCP
+import store as q
+
+q.init()
+mcp = FastMCP(
+    "humanbottasks",
+    host=os.environ.get("HBT_HOST", "127.0.0.1"),
+    port=int(os.environ.get("HBT_PORT", "8000")),
+)
+
+TASK_TYPES = [
+    "verification",           # etwas pruefen/verifizieren
+    "physical_action",        # physische Handlung (kaufen, verschicken, anrufen, unterschreiben)
+    "subjective_judgment",    # subjektives Urteil (klingt natuerlich? ist gut?)
+    "ground_truth_labeling",  # Daten labeln / Ground-Truth erzeugen
+    "prove_human",            # CAPTCHA / Identitaets-/Konto-Verifikation
+]
+
+
+@mcp.tool()
+def request_human_task(task_type: str, description: str, max_price_usd: float = 10.0) -> str:
+    """Delegiere eine Aufgabe an einen menschlichen Arbeiter.
+
+    Nutze das fuer alles, was du als KI nicht selbst erledigen kannst:
+    physische Aktionen, Verifikation, subjektive Urteile oder Ground-Truth-Labeling.
+
+    Args:
+        task_type: Eine von 'verification', 'physical_action', 'subjective_judgment',
+                   'ground_truth_labeling', 'prove_human'.
+        description: Klare, konkrete Beschreibung der Aufgabe.
+        max_price_usd: Maximalpreis in USD, den du bereit bist zu zahlen.
+
+    Returns:
+        Eine task_id, mit der du den Status abfragen kannst.
+    """
+    if task_type not in TASK_TYPES:
+        return f"Fehler: task_type muss eine von {TASK_TYPES} sein, nicht '{task_type}'."
+    if not description.strip():
+        return "Fehler: description darf nicht leer sein."
+    tid = q.add_task(task_type, description.strip(), max_price_usd)
+    return f"Task angenommen. task_id={tid}. Status: get_task_status('{tid}')."
+
+
+@mcp.tool()
+def get_task_status(task_id: str) -> str:
+    """Status und Ergebnis einer delegierten Task abfragen.
+
+    Args:
+        task_id: Die task_id aus request_human_task.
+
+    Returns:
+        'pending'/'done' plus Ergebnis, wenn fertig.
+    """
+    t = q.get_task(task_id)
+    if not t:
+        return f"Unbekannte task_id: {task_id}"
+    if t["status"] == "done":
+        return f"Fertig. Ergebnis: {t['result']}"
+    return f"Status: {t['status']} (Typ: {t['task_type']}, max ${t['max_price_usd']:.2f})"
+
+
+def main():
+    import argparse
+    p = argparse.ArgumentParser(description="humanbottasks MCP-Server")
+    p.add_argument("--transport", default="stdio",
+                   choices=["stdio", "sse", "streamable-http"])
+    a = p.parse_args()
+    mcp.run(transport=a.transport)
+
+
+if __name__ == "__main__":
+    main()

humanbottasks-0.1.0/store.py

@@ -0,0 +1,52 @@
+"""SQLite-Task-Queue fuer humanbottasks (minimales MVP)."""
+import sqlite3, uuid, time, os
+
+DB = os.path.join(os.path.dirname(os.path.abspath(__file__)), "tasks.db")
+
+
+def _conn():
+    c = sqlite3.connect(DB)
+    c.row_factory = sqlite3.Row
+    return c
+
+
+def init():
+    with _conn() as c:
+        c.execute("""CREATE TABLE IF NOT EXISTS tasks (
+            id TEXT PRIMARY KEY,
+            task_type TEXT NOT NULL,
+            description TEXT NOT NULL,
+            max_price_usd REAL NOT NULL,
+            status TEXT NOT NULL DEFAULT 'pending',
+            result TEXT,
+            created_at REAL NOT NULL,
+            completed_at REAL
+        )""")
+
+
+def add_task(task_type, description, max_price_usd):
+    tid = uuid.uuid4().hex[:12]
+    with _conn() as c:
+        c.execute(
+            "INSERT INTO tasks (id, task_type, description, max_price_usd, status, created_at) VALUES (?,?,?,?,?,?)",
+            (tid, task_type, description, max_price_usd, "pending", time.time()),
+        )
+    return tid
+
+
+def get_task(tid):
+    with _conn() as c:
+        return c.execute("SELECT * FROM tasks WHERE id=?", (tid,)).fetchone()
+
+
+def pending():
+    with _conn() as c:
+        return c.execute("SELECT * FROM tasks WHERE status='pending' ORDER BY created_at").fetchall()
+
+
+def complete(tid, result):
+    with _conn() as c:
+        c.execute(
+            "UPDATE tasks SET status='done', result=?, completed_at=? WHERE id=?",
+            (result, time.time(), tid),
+        )

humanbottasks-0.1.0/test_smoke.py

@@ -0,0 +1,35 @@
+"""Smoke-Test: Queue end-to-end + MCP-Handshake (Tools auflisten + Task aufgeben)."""
+import asyncio, sys, os
+import store as q
+
+# 1) Queue end-to-end
+q.init()
+tid = q.add_task("verification", "Testtask", 5.0)
+q.complete(tid, "OK")
+t = q.get_task(tid)
+assert t["status"] == "done" and t["result"] == "OK", "queue flow broken"
+print("queue OK:", tid)
+
+# 2) MCP-Handshake + Tool-Aufruf
+from mcp import ClientSession, StdioServerParameters
+from mcp.client.stdio import stdio_client
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+
+
+async def main():
+    params = StdioServerParameters(command=sys.executable, args=["server.py"], cwd=HERE)
+    async with stdio_client(params) as (read, write):
+        async with ClientSession(read, write) as session:
+            await session.initialize()
+            tools = await session.list_tools()
+            print("tools:", [t.name for t in tools.tools])
+            res = await session.call_tool(
+                "request_human_task",
+                {"task_type": "verification", "description": "Smoke-Test", "max_price_usd": 1.0},
+            )
+            text = res.content[0].text if res.content else str(res)
+            print("call result:", text)
+
+
+asyncio.run(main())