convez.ai
MCP Server
Tomer-Barak

human-delegation

Tomer-Barak/human-delegation

Ver no GitHub
InicialPluginScore · de 0 a 100

MCP server that gives agentic harnesses a human-delegation tool

Instalação

$npx convez-ai Tomer-Barak/human-delegation

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
28%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
1

README

A tradução para o português deste README ainda está na fila.

Delegate to Human

An MCP server that gives agentic harnesses a human-delegation tool. Agents discover registered humans, delegate asynchronous tasks, answer clarification questions, and accept or request revisions to submitted results.

Humans receive and answer work through:

  • Web: authenticated inbox with threaded messages, result submission, and files.
  • Email: assignment notification with a one-time secure web link.
  • Telegram: bot notifications and /question, /message, and /result replies.

Architecture

The service is harness-neutral. It exposes seven MCP tools over Streamable HTTP:

ToolPurpose
list_humansDiscover active humans, skills, availability, and channels
delegate_to_humanCreate an asynchronous task for a specific human
get_human_taskRead task status, thread, result, and attachment links
list_human_tasksList tasks created by the current agent API key
message_humanAnswer questions or add task context
review_human_resultAccept a result or request revision
cancel_human_taskCancel unfinished work

The task lifecycle is:

pending_delivery -> awaiting_human
awaiting_human -> awaiting_agent -> awaiting_human
awaiting_human -> awaiting_agent_review -> completed
awaiting_agent_review -> awaiting_human  (revision requested)

declined, expired, canceled, and delivery_failed are terminal states.

Local setup

Requirements: Node.js 24+, pnpm 11+, and SQLite-compatible native build support.

pnpm install
cp .env.example .env

Generate secrets and place them in .env:

openssl rand -base64 32   # ENCRYPTION_KEY
openssl rand -hex 32      # TOKEN_SECRET
openssl rand -hex 32      # ADMIN_TOKEN

Build and run:

pnpm build
pnpm start

Note: static assets are content-hashed and enumerated at server start. Always rebuild before starting (or restart after a rebuild) — rebuilding the web bundle under an already-running server serves stale assets.

Open:

  • Human inbox: http://localhost:3000/
  • Admin console: http://localhost:3000/admin
  • MCP endpoint: http://localhost:3000/mcp
  • Health check: http://localhost:3000/health

The admin console uses ADMIN_TOKEN. Create at least one human profile and one API key there. The raw API key is shown once.

For development, run the API and Vite dev server together:

pnpm dev

The UI is then at http://localhost:5173; /api requests are proxied to port 3000.

MCP client configuration

Configure any Streamable HTTP MCP client with:

{
  "url": "http://localhost:3000/mcp",
  "headers": {
    "Authorization": "Bearer dth_REPLACE_WITH_ISSUED_KEY"
  }
}

For harnesses that only launch local stdio MCP servers, use an HTTP-to-MCP bridge and pass the same URL and authorization header. The service itself intentionally does not depend on a particular agent harness.

The intended agent flow is:

  1. Call list_humans.
  2. Call delegate_to_human with an explicit human_id.
  3. Continue other work and periodically call get_human_task.
  4. When the task is awaiting_agent, use message_human.
  5. When it is awaiting_agent_review, call review_human_result.

Channel configuration

Channel credentials are encrypted at rest with AES-256-GCM using ENCRYPTION_KEY. Each human has an ordered preference list. If a preferred channel fails, delivery falls back to the next configured channel. An explicit channel in delegate_to_human is strict and does not fall back.

Email

Set SMTP_HOST, SMTP_PORT, SMTP_FROM, and optional authentication values in .env. Email is outbound-only; recipients answer through the secure web link.

Telegram

Set:

TELEGRAM_BOT_TOKEN=...
TELEGRAM_WEBHOOK_SECRET=...

Register the webhook after the service is publicly reachable:

curl -X POST "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/setWebhook" \
  -H "content-type: application/json" \
  -d "{
    \"url\": \"https://YOUR_HOST/api/telegram/webhook\",
    \"secret_token\": \"${TELEGRAM_WEBHOOK_SECRET}\"
  }"

Add the recipient's numeric Telegram chat ID to their admin profile. The bot accepts:

/question TASK_UUID clarification needed
/message TASK_UUID progress update
/result TASK_UUID final result

Files are uploaded and downloaded through signed web links rather than native email or Telegram attachments.

Docker

cp .env.example .env
# Fill in required secrets.
docker compose up --build

SQLite and attachments persist under ./data, mounted at /app/data.

Security model

  • Agent API keys are stored only as SHA-256 hashes and can be revoked.
  • Human web sessions use signed, HTTP-only cookies.
  • Email and generated admin login links are one-time and expire.
  • Attachment URLs are task-scoped and expire.
  • Telegram webhook updates are deduplicated and bound to configured chat IDs.
  • Channel credentials use authenticated encryption at rest.
  • Task data is isolated by the API key that created it and the assigned human.

Run verification with:

pnpm typecheck
pnpm test
pnpm build
Ver o original no GitHub

Relacionados