feat(megazord): paperclip-mcp — operar a orquestração do Paperclip por MCP - #7
Merged
Merged
Conversation
…on plane Track A of the Paperclip control-plane: an MCP (stdio) server that lets an agent OPERATE Paperclip/T3 as tools, wrapping the proven MegazordT3DispatchClient (same origin-resolve + scoped-token-mint + HTTP path as t3-dispatch). Tools: paperclip_run (spawn agent / run task as a routed thread), paperclip_snapshot (live orchestration state — foundation for monitoring/ resilience), paperclip_thread_status, paperclip_thread_continue, paperclip_accounts (instances + quota). Transport: newline-delimited JSON-RPC 2.0 on stdio. Token minted at runtime, never written to disk. Verified live: initialize + tools/list + a snapshot call returned the real orchestration snapshot (projects/threads). Native routines/scheduling land on top of this next (Bruno's decision 2026-09-14: build routines natively in the local layer, not reverse-engineer the T3 cloud). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
CORRECTION to earlier discovery: routines are NOT a cloud black box. They are a LOCAL HTTP API on the isolated company instance (Paperclip acp-engine, default :3100), unauthenticated. The 31 native routines already exist (created by capiva-factory/scripts/native-routines-setup.mjs), all with schedule triggers DISABLED by Bruno's credit-safety mandate. Adds read tools: paperclip_routine_list (id/title/status/scheduleEnabled/cron), paperclip_routine_get (full routine). Verified live via the MCP: routine_list returned all 31 with enabled=false. Track B (native routines) is therefore "wire the existing local API", not build from scratch nor reverse-engineer the cloud. enable/disable/run-now tools come next (need the trigger-update + run endpoints); enabling stays Bruno's decision. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Endpoints discovered in capiva-factory/paperclip-upstream (the full Paperclip
source) cli/commands/client/routine-api.ts:
- GET /api/routines/{id}/runs -> run history (resilience signal)
- POST /api/routines/{id}/run {source:manual} -> ad-hoc run (works with trigger
DISABLED; single manual run)
- PATCH /api/routine-triggers/{triggerId} {enabled} -> enable/disable auto-fire
Adds tools: paperclip_routine_runs, paperclip_routine_run, paperclip_routine_
set_schedule (resolves the schedule trigger from the routine, then PATCHes it).
Enabling costs credit and stays Bruno's explicit decision — never auto-enabled.
Verified live (credit-safe): routine_runs -> [] for a disabled routine;
set_schedule{enabled:false} no-op returned the triggerId (PATCH works, no state
change). 10 tools total now, operating BOTH local planes (:3773 orchestration,
:3100 company/routines).
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Track C detection core. One tool that probes the control-plane for the signals
Bruno asked to monitor:
- backends reachable (:3773 orchestration, :3100 routines) with latency
- enabled routines running on time (via /routines/{id}/runs): flag failed or
no-completed-run-in-N-hours
- stuck threads (from the snapshot): running/starting longer than N minutes
Returns findings ranked by severity + a healthy flag.
Verified live: healthy=true, both backends ok, 31 routines/0 enabled, 16 threads
by state, 0 findings. 11 tools total. The scheduling supervisor loop (alert +
heal) pairs this sweep with an alert channel next.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Standalone scheduled process (independent of the agent session, so it detects problems even when the session is down). Runs the health sweep, writes ~/.cache/paperclip-supervisor/health.json, and ALERTS the WhatsApp control group when there are findings (backend down, routine run failed/missed, stuck thread). Flags: --dry-run (print alert instead of send), --heal (retry a routine whose last run FAILED — off by default, since retrying costs credit). Alert reuses the existing whatsapp bridge (POST :8080/api/send + bridge token). Exit: 0 healthy, 1 findings, 2 backend down, 3 error. Verified via --dry-run: healthy=true, both backends up, clean exit 0 (process.exitCode instead of process.exit to avoid the libuv teardown assertion from the token-mint child). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
O que
Track A do control-plane do Paperclip: um servidor MCP (stdio) que deixa o agente OPERAR o Paperclip/T3 como tools, embrulhando o
MegazordT3DispatchClientjá provado (mesmo origin-resolve + mint de token com escopo + HTTP dot3-dispatch).Tools
paperclip_run— spawn de agent / rodar task como thread roteada (ad-hoc run).paperclip_snapshot— estado vivo de orquestração (base do monitor/resiliência).paperclip_thread_status/paperclip_thread_continue— ciclo de vida de thread.paperclip_accounts— instâncias (agents) + quota.Verificação
Rodado ao vivo por stdio:
initialize+tools/list(5 tools) +paperclip_snapshotretornou o snapshot real de orquestração (projects/threads,snapshotSequence). Token mintado em runtime, nunca escrito em disco.Contexto
Parte do projeto "operar todo o Paperclip por MCP/CLI" (spec em
capiva-factory/PAPERCLIP-CONTROL-PLANE-SPEC.md). As rotinas nativas entram por cima disto (decisão do Bruno 2026-09-14: construir rotinas no local, não reverter a API cloud SaaS). Próximo: scheduler/rotinas nativas + supervisor de resiliência.🤖 Generated with Claude Code