mcp-paperclip/SPEC.md

title, date, type, status, project, desk_task, tags

title	date	type	status	project	desk_task	tags
SPEC — MCP Paperclip v1.0	2026-04-07	spec	draft	mcp-paperclip		mcp paperclip typescript agentes orquestração

SPEC — MCP Paperclip v1.0

MCP TypeScript para integração completa com o Paperclip AI (orquestrador autónomo em clip.descomplicar.pt).

Permite ao Claude Code gerir agentes, issues, rotinas, goals, projectos, aprovações, custos, actividade, skills, segredos e dashboard via API REST.

---

Contexto

Item	Valor
API Base	https://clip.descomplicar.pt/api (produção)
Paperclip Version	0.3.1
Company ID	ebe10308-efd7-453f-86ab-13e6fe84004f (Descomplicar)
User ID	v1N5OccPn9DGq6iog7qW9nEvnXYFT3iO (Emanuel)
Auth	Authorization: Bearer {PAPERCLIP_API_KEY} (Board API Key, SHA256 hash em board_api_keys)
Destino	/home/ealmeida/mcp-servers/mcp-paperclip/
Transport	STDIO (Claude Code) + StreamableHTTP porta 3168 + SSE porta 3168 (legado)
Linguagem	TypeScript (padrão Descomplicar)
API Total	246 endpoints em 21 módulos — este MCP cobre 159 tools

---

Pré-requisito: Criar Board API Key

Antes da primeira utilização, gerar e registar uma Board API Key:

# Gerar key
KEY=$(node -e "console.log('pcp_mcp_' + require('crypto').randomBytes(24).toString('hex'))")
echo "PAPERCLIP_API_KEY=$KEY"

# Registar na BD (SHA256 hash)
HASH=$(node -e "const c=require('crypto'); process.argv[1] && console.log(c.createHash('sha256').update(process.argv[1]).digest('hex'))" "$KEY")
PGPASSWORD=paperclip psql -h 127.0.0.1 -p 54329 -U paperclip -d paperclip -c \
  "INSERT INTO board_api_keys (user_id, name, key_hash) VALUES ('v1N5OccPn9DGq6iog7qW9nEvnXYFT3iO', 'claude-code-mcp', '$HASH');"

Guardar KEY no .env do MCP como PAPERCLIP_API_KEY.

---

Arquitectura

mcp-paperclip/
├── src/
│   ├── index.ts              # Entry STDIO (Claude Code)
│   ├── index-http.ts         # Entry StreamableHTTP + SSE porta 3175
│   ├── server.ts             # Lógica comum (createServer)
│   ├── client.ts             # HTTP client para API Paperclip
│   ├── tools/
│   │   ├── index.ts          # Registar todas as tools
│   │   ├── agents.ts         # Agentes — CRUD, lifecycle, config, keys, heartbeats
│   │   ├── issues.ts         # Issues — CRUD, comments, documents, work-products, labels
│   │   ├── routines.ts       # Rotinas — CRUD, triggers, runs
│   │   ├── goals.ts          # Goals — CRUD
│   │   ├── projects.ts       # Projectos — CRUD, workspaces
│   │   ├── approvals.ts      # Aprovações — governance workflow
│   │   ├── costs.ts          # Custos e budgets — monitorização financeira
│   │   ├── activity.ts       # Actividade — audit log
│   │   ├── skills.ts         # Company skills — gestão de competências
│   │   ├── secrets.ts        # Segredos — gestão de secrets encriptados
│   │   ├── plugins.ts        # Plugins — instalar, activar, config, health
│   │   ├── assets.ts         # Assets — upload imagens e logos
│   │   ├── settings.ts       # Instance settings — configuração geral
│   │   ├── access.ts         # Invites, join requests, members
│   │   ├── company.ts        # Company, org, dashboard, members
│   │   └── health.ts         # Health check
│   └── utils/
│       ├── logger.ts         # Logger MCP-compatible (stderr, sem cores)
│       └── annotations.ts    # inferAnnotations por prefixo
├── tests/
│   └── tools.test.ts
├── docs/
│   └── API_REFERENCE.md      # Endpoints mapeados
├── scripts/
│   ├── validate-capabilities.sh
│   └── create-api-key.sh     # Script criação Board API Key
├── .gitea/workflows/
│   └── ci.yml
├── .env.example
├── .eslintrc / eslint.config.js
├── .prettierrc
├── tsconfig.json
├── package.json
├── CLAUDE.md
├── CHANGELOG.md
└── README.md

---

Tools (159 total)

1. Health (1 tool)

Tool	Método	Endpoint	Tipo
get_health	GET	/health	read

Retorna: { status, version, deploymentMode, bootstrapStatus }

---

2. Company / Org (10 tools)

Tool	Método	Endpoint	Tipo
get_company	GET	/companies/:id	read
list_companies	GET	/companies	read
get_company_stats	GET	/companies/stats	read
update_company	PATCH	/companies/:id	write
update_company_branding	PATCH	/companies/:id/branding	write
get_org_chart	GET	/companies/:id/org	read
get_dashboard	GET	/companies/:id/dashboard	read
list_members	GET	/companies/:id/members	read
update_member_permissions	PATCH	/companies/:id/members/:memberId/permissions	write
get_sidebar_badges	GET	/companies/:id/sidebar-badges	read

Nota: get_org_chart retorna JSON da hierarquia, não SVG.

---

3. Agentes (22 tools)

Tool	Método	Endpoint	Tipo
list_agents	GET	/companies/:id/agents	read
get_agent	GET	/agents/:id	read
get_agent_runtime_state	GET	/agents/:id/runtime-state	read
get_agent_configuration	GET	/agents/:id/configuration	read
get_agent_config_revisions	GET	/agents/:id/config-revisions	read
rollback_agent_config	POST	/agents/:id/config-revisions/:revisionId/rollback	write
get_agent_skills	GET	/agents/:id/skills	read
sync_agent_skills	POST	/agents/:id/skills/sync	write
get_agent_task_sessions	GET	/agents/:id/task-sessions	read
get_agent_instructions_bundle	GET	/agents/:id/instructions-bundle	read
update_agent_instructions_bundle	PATCH	/agents/:id/instructions-bundle	write
create_agent	POST	/companies/:id/agents	write
create_agent_hire	POST	/companies/:id/agent-hires	write
update_agent	PATCH	/agents/:id	write
update_agent_permissions	PATCH	/agents/:id/permissions	write
update_agent_instructions_path	PATCH	/agents/:id/instructions-path	write
pause_agent	POST	/agents/:id/pause	write
resume_agent	POST	/agents/:id/resume	write
wakeup_agent	POST	/agents/:id/wakeup	write
invoke_agent_heartbeat	POST	/agents/:id/heartbeat/invoke	write
terminate_agent	POST	/agents/:id/terminate	destrutivo
delete_agent	DELETE	/agents/:id	destrutivo

Parâmetros create_agent:

{
  name: string,          // nome do agente
  role: string,          // ceo | coo | cto | engineer | analyst | devops | pm | ...
  title?: string,        // descrição do cargo
  reports_to?: string,   // UUID do agente supervisor
  capabilities?: string, // texto livre
  model?: string,        // claude-sonnet-4-6 | claude-opus-4-6 | ...
  budget_monthly_cents?: number,
  instructions_file_path?: string  // path absoluto para AGENTS.md
}

Parâmetros create_agent_hire:

{
  name: string,
  role: string,
  title?: string,
  reports_to?: string,
  // Passa por governance/approval antes de criar o agente
}

Parâmetros wakeup_agent:

{
  agent_id: string,
  issue_id?: string,   // acordar em contexto de issue específica
  message?: string     // mensagem de contexto
}

---

4. Agent Keys (3 tools)

Tool	Método	Endpoint	Tipo
list_agent_keys	GET	/agents/:id/keys	read
create_agent_key	POST	/agents/:id/keys	write
delete_agent_key	DELETE	/agents/:id/keys/:keyId	destrutivo

---

5. Heartbeat Runs (6 tools)

Tool	Método	Endpoint	Tipo
list_heartbeat_runs	GET	/companies/:id/heartbeat-runs	read
list_live_runs	GET	/companies/:id/live-runs	read
get_heartbeat_run	GET	/heartbeat-runs/:runId	read
get_heartbeat_run_events	GET	/heartbeat-runs/:runId/events	read
get_heartbeat_run_log	GET	/heartbeat-runs/:runId/log	read
cancel_heartbeat_run	POST	/heartbeat-runs/:runId/cancel	write

---

6. Issues (17 tools)

Tool	Método	Endpoint	Tipo
list_issues	GET	/companies/:id/issues	read
get_issue	GET	/issues/:id	read
get_issue_heartbeat_context	GET	/issues/:id/heartbeat-context	read
create_issue	POST	/companies/:id/issues	write
update_issue	PATCH	/issues/:id	write
delete_issue	DELETE	/issues/:id	destrutivo
checkout_issue	POST	/issues/:id/checkout	write
release_issue	POST	/issues/:id/release	write
get_issue_comments	GET	/issues/:id/comments	read
add_issue_comment	POST	/issues/:id/comments	write
list_issue_documents	GET	/issues/:id/documents	read
get_issue_document	GET	/issues/:id/documents/:key	read
upsert_issue_document	PUT	/issues/:id/documents/:key	write
delete_issue_document	DELETE	/issues/:id/documents/:key	destrutivo
list_issue_work_products	GET	/issues/:id/work-products	read
create_issue_work_product	POST	/issues/:id/work-products	write
list_issue_live_runs	GET	/issues/:id/live-runs	read

Parâmetros create_issue:

{
  title: string,
  description?: string,  // markdown
  assignee_id?: string,  // UUID do agente
  priority?: 'low' | 'medium' | 'high' | 'urgent',
  labels?: string[]
}

Nota: Issues são a forma principal de dar trabalho aos agentes. checkout_issue -> agente bloqueia e começa a trabalhar. release_issue -> agente liberta e fica idle.

---

7. Labels (3 tools)

Tool	Método	Endpoint	Tipo
list_labels	GET	/companies/:id/labels	read
create_label	POST	/companies/:id/labels	write
delete_label	DELETE	/labels/:labelId	destrutivo

---

8. Issue Attachments (4 tools)

Tool	Método	Endpoint	Tipo
list_issue_attachments	GET	/issues/:id/attachments	read
upload_issue_attachment	POST	/companies/:id/issues/:issueId/attachments	write
get_attachment_content	GET	/attachments/:attachmentId/content	read
delete_attachment	DELETE	/attachments/:attachmentId	destrutivo

---

9. Approvals / Governance (10 tools)

Tool	Método	Endpoint	Tipo
list_approvals	GET	/companies/:id/approvals	read
get_approval	GET	/approvals/:id	read
create_approval	POST	/companies/:id/approvals	write
list_approval_issues	GET	/approvals/:id/issues	read
approve_approval	POST	/approvals/:id/approve	write
reject_approval	POST	/approvals/:id/reject	write
request_approval_revision	POST	/approvals/:id/request-revision	write
resubmit_approval	POST	/approvals/:id/resubmit	write
list_approval_comments	GET	/approvals/:id/comments	read
add_approval_comment	POST	/approvals/:id/comments	write

---

10. Rotinas (8 tools)

Tool	Método	Endpoint	Tipo
list_routines	GET	/companies/:id/routines	read
get_routine	GET	/routines/:id	read
create_routine	POST	/companies/:id/routines	write
update_routine	PATCH	/routines/:id	write
list_routine_runs	GET	/routines/:id/runs	read
run_routine	POST	/routines/:id/run	write
create_routine_trigger	POST	/routines/:id/triggers	write
delete_routine_trigger	DELETE	/routine-triggers/:id	destrutivo

---

11. Goals (5 tools)

Tool	Método	Endpoint	Tipo
list_goals	GET	/companies/:id/goals	read
get_goal	GET	/goals/:id	read
create_goal	POST	/companies/:id/goals	write
update_goal	PATCH	/goals/:id	write
delete_goal	DELETE	/goals/:id	destrutivo

---

12. Projectos (7 tools)

Tool	Método	Endpoint	Tipo
list_projects	GET	/companies/:id/projects	read
get_project	GET	/projects/:id	read
create_project	POST	/companies/:id/projects	write
update_project	PATCH	/projects/:id	write
delete_project	DELETE	/projects/:id	destrutivo
list_project_workspaces	GET	/projects/:id/workspaces	read
create_project_workspace	POST	/projects/:id/workspaces	write

---

13. Costs / Budgets (12 tools)

Tool	Método	Endpoint	Tipo
get_cost_summary	GET	/companies/:id/costs/summary	read
get_costs_by_agent	GET	/companies/:id/costs/by-agent	read
get_costs_by_agent_model	GET	/companies/:id/costs/by-agent-model	read
get_costs_by_provider	GET	/companies/:id/costs/by-provider	read
get_costs_by_project	GET	/companies/:id/costs/by-project	read
get_finance_summary	GET	/companies/:id/costs/finance-summary	read
list_finance_events	GET	/companies/:id/costs/finance-events	read
get_window_spend	GET	/companies/:id/costs/window-spend	read
get_quota_windows	GET	/companies/:id/costs/quota-windows	read
get_budgets_overview	GET	/companies/:id/budgets/overview	read
update_company_budget	PATCH	/companies/:id/budgets	write
update_agent_budget	PATCH	/agents/:agentId/budgets	write

---

14. Activity / Audit Log (4 tools)

Tool	Método	Endpoint	Tipo
list_company_activity	GET	/companies/:id/activity	read
create_activity_entry	POST	/companies/:id/activity	write
list_issue_activity	GET	/issues/:id/activity	read
list_issue_runs	GET	/issues/:id/runs	read

---

15. Company Skills (6 tools)

Tool	Método	Endpoint	Tipo
list_company_skills	GET	/companies/:id/skills	read
get_company_skill	GET	/companies/:id/skills/:skillId	read
list_skill_files	GET	/companies/:id/skills/:skillId/files	read
create_company_skill	POST	/companies/:id/skills	write
import_company_skill	POST	/companies/:id/skills/import	write
delete_company_skill	DELETE	/companies/:id/skills/:skillId	destrutivo

---

16. Secrets (5 tools)

Tool	Método	Endpoint	Tipo
list_secrets	GET	/companies/:id/secrets	read
list_secret_providers	GET	/companies/:id/secret-providers	read
create_secret	POST	/companies/:id/secrets	write
rotate_secret	POST	/secrets/:id/rotate	write
delete_secret	DELETE	/secrets/:id	destrutivo

---

17. Execution Workspaces (3 tools)

Tool	Método	Endpoint	Tipo
list_execution_workspaces	GET	/companies/:id/execution-workspaces	read
get_execution_workspace	GET	/execution-workspaces/:id	read
update_execution_workspace	PATCH	/execution-workspaces/:id	write

---

18. Adapters / Models (2 tools)

Tool	Método	Endpoint	Tipo
list_adapter_models	GET	/companies/:id/adapters/:type/models	read
test_adapter_environment	POST	/companies/:id/adapters/:type/test-environment	write

---

19. Portability / Export-Import (2 tools)

Tool	Método	Endpoint	Tipo
export_company	POST	/companies/:id/exports	write
import_company_preview	POST	/companies/:id/imports/preview	read

---

20. Plugins (17 tools)

Tool	Método	Endpoint	Tipo
list_plugins	GET	/plugins	read
get_plugin	GET	/plugins/:pluginId	read
list_plugin_examples	GET	/plugins/examples	read
list_plugin_tools	GET	/plugins/tools	read
install_plugin	POST	/plugins/install	write
delete_plugin	DELETE	/plugins/:pluginId	destrutivo
enable_plugin	POST	/plugins/:pluginId/enable	write
disable_plugin	POST	/plugins/:pluginId/disable	write
upgrade_plugin	POST	/plugins/:pluginId/upgrade	write
get_plugin_health	GET	/plugins/:pluginId/health	read
get_plugin_logs	GET	/plugins/:pluginId/logs	read
get_plugin_config	GET	/plugins/:pluginId/config	read
set_plugin_config	POST	/plugins/:pluginId/config	write
test_plugin_config	POST	/plugins/:pluginId/config/test	write
get_plugin_dashboard	GET	/plugins/:pluginId/dashboard	read
list_plugin_jobs	GET	/plugins/:pluginId/jobs	read
trigger_plugin_job	POST	/plugins/:pluginId/jobs/:jobId/trigger	write

---

21. Assets (3 tools)

Tool	Método	Endpoint	Tipo
upload_image_asset	POST	/companies/:id/assets/images	write
upload_company_logo	POST	/companies/:id/logo	write
get_asset_content	GET	/assets/:assetId/content	read

Nota: Uploads usam multipart/form-data.

---

22. Instance Settings (4 tools)

Tool	Método	Endpoint	Tipo
get_general_settings	GET	/instance/settings/general	read
update_general_settings	PATCH	/instance/settings/general	write
get_experimental_settings	GET	/instance/settings/experimental	read
update_experimental_settings	PATCH	/instance/settings/experimental	write

---

23. Invites / Onboarding (7 tools)

Tool	Método	Endpoint	Tipo
create_invite	POST	/companies/:id/invites	write
get_invite	GET	/invites/:token	read
get_invite_onboarding	GET	/invites/:token/onboarding	read
accept_invite	POST	/invites/:token/accept	write
revoke_invite	POST	/invites/:inviteId/revoke	write
list_join_requests	GET	/companies/:id/join-requests	read
approve_join_request	POST	/companies/:id/join-requests/:requestId/approve	write

---

24. Plugin Bridge / Execution (4 tools)

Tool	Método	Endpoint	Tipo
execute_plugin_tool	POST	/plugins/tools/execute	write
plugin_bridge_data	POST	/plugins/:pluginId/bridge/data	read
plugin_bridge_action	POST	/plugins/:pluginId/bridge/action	write
list_ui_contributions	GET	/plugins/ui-contributions	read

---

Endpoints Excluídos (não implementados como tools)

Módulo	Razão
CLI Auth (challenges, approve, cancel, revoke)	Fluxo interactivo browser-based — não adequado para MCP
Board Claims (get/claim token)	Fluxo de setup inicial — uma vez por instalação
LLMs (/llms/*.txt)	Documentação estática — aceder directamente via HTTP
Plugin SSE Stream (/plugins/:id/bridge/stream/:channel)	SSE stream contínuo — não compatível com request/response MCP
Admin Operations (promote/demote instance admin, user company access)	Operações privilegiadas de super-admin — proteger de uso acidental

---

Variáveis de Ambiente

# .env.example
PAPERCLIP_API_URL=https://clip.descomplicar.pt/api
PAPERCLIP_API_KEY=pcp_mcp_...          # Board API Key gerada pelo script
PAPERCLIP_COMPANY_ID=ebe10308-efd7-453f-86ab-13e6fe84004f

# HTTP/SSE transport
HTTP_PORT=3168

PAPERCLIP_COMPANY_ID injectado automaticamente nas tools que precisam de :companyId, sem obrigar o utilizador a passá-lo em cada chamada.

---

Cliente HTTP (src/client.ts)

export class PaperclipClient {
  private baseUrl: string;
  private companyId: string;
  private headers: Record<string, string>;

  constructor() {
    this.baseUrl = process.env.PAPERCLIP_API_URL ?? 'https://clip.descomplicar.pt/api';
    this.companyId = process.env.PAPERCLIP_COMPANY_ID ?? '';
    this.headers = {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${process.env.PAPERCLIP_API_KEY}`,
    };
  }

  async get<T>(path: string, params?: Record<string, string>): Promise<T>
  async post<T>(path: string, body?: unknown): Promise<T>
  async patch<T>(path: string, body?: unknown): Promise<T>
  async put<T>(path: string, body?: unknown): Promise<T>
  async delete<T>(path: string): Promise<T>

  // Helpers com company_id injectado
  companyPath(suffix: string): string {
    return `/companies/${this.companyId}${suffix}`;
  }
}

---

Tool Annotations

// Aplicar inferAnnotations() a todas as tools:
// list_*, get_* → readOnlyHint: true
// delete_*, terminate_* → destructiveHint: true
// update_*, patch_* → idempotentHint: true
// create_*, add_*, checkout_*, release_*, approve_*, reject_* → write normal
// run_*, invoke_*, wakeup_*, fire_* → write (side-effects)

---

Configuração ~/.claude.json

{
  "mcpServers": {
    "paperclip": {
      "command": "node",
      "args": ["/home/ealmeida/mcp-servers/mcp-paperclip/dist/index.js"],
      "env": {
        "PAPERCLIP_API_URL": "https://clip.descomplicar.pt/api",
        "PAPERCLIP_API_KEY": "pcp_mcp_...",
        "PAPERCLIP_COMPANY_ID": "ebe10308-efd7-453f-86ab-13e6fe84004f"
      }
    }
  }
}

---

Plano de Implementação (6 sprints)

Sprint 1 — Fundação + Health + Agentes (read-only)

Objectivo: MCP operacional com tools de leitura base

• npm init + dependências (@modelcontextprotocol/sdk, zod, dotenv, winston)
• DevDeps: TypeScript, ESLint, Prettier, Jest, Husky
• tsconfig.json, eslint.config.js, .prettierrc, .gitignore
• src/client.ts — PaperclipClient com auth Bearer e métodos GET/POST/PATCH/PUT/DELETE
• src/utils/logger.ts — logger MCP-compatible (stderr, sem cores)
• src/utils/annotations.ts — inferAnnotations
• src/server.ts — createServer com capabilities completas
• src/index.ts — entry STDIO
• src/index-http.ts — entry StreamableHTTP + SSE porta 3175 (stateless)
• scripts/create-api-key.sh — script criação Board API Key
• Tools health.ts: get_health
• Tools company.ts: get_company, list_companies, get_company_stats, get_org_chart, get_dashboard, get_sidebar_badges
• Tools agents.ts (read): list_agents, get_agent, get_agent_runtime_state, get_agent_configuration, get_agent_config_revisions, get_agent_skills, get_agent_task_sessions, get_agent_instructions_bundle
• .env.example, CLAUDE.md, CHANGELOG.md, README.md
• Testes básicos das tools read
• npm run quality:check passa
• Repo Gitea criado, CI verde

Critério de aceitação Sprint 1: list_agents devolve os 64 agentes da Descomplicar via STDIO.

---

Sprint 2 — Issues + Write Operations Agentes

Objectivo: CRUD completo de issues e operações write em agentes

• Tools issues.ts: list, get, create, update, delete, comments, checkout, release, documents, work-products, heartbeat-context, live-runs (17 tools)
• Tools labels.ts: list, create, delete (3 tools)
• Tools attachments.ts: list, upload, get_content, delete (4 tools)
• Tools agents.ts (write): create, create_hire, update, update_permissions, update_instructions_path, update_instructions_bundle, rollback_config, sync_skills, pause, resume, wakeup, invoke_heartbeat, terminate, delete (14 tools)
• Tools agent_keys.ts: list, create, delete (3 tools)
• Validação Zod em inputs de write
• Tratamento de erros HTTP (401, 403, 404, 422) -> mensagens úteis
• Testes issues e write ops
• Actualizar ~/.claude.json com MCP configurado
• Smoke test: criar issue, atribuir ao Reality Checker, fazer checkout

Critério de aceitação Sprint 2: Claude Code consegue criar uma issue, assignar a um agente e fazer checkout via MCP.

---

Sprint 3 — Routines, Goals, Projects, Approvals

Objectivo: Workflows completos de gestão e governance

• Tools routines.ts: list, get, create, update, list_runs, run, create_trigger, delete_trigger (8 tools)
• Tools goals.ts: list, get, create, update, delete (5 tools)
• Tools projects.ts: list, get, create, update, delete, list_workspaces, create_workspace (7 tools)
• Tools approvals.ts: list, get, create, list_issues, approve, reject, request_revision, resubmit, comments (10 tools)
• Testes de workflows: criar goal -> criar issue -> aprovar -> executar

Critério de aceitação Sprint 3: Workflow completo de governance: criar approval, aprovar, verificar estado.

---

Sprint 4 — Costs, Activity, Skills, Secrets, Workspaces

Objectivo: Observabilidade e gestão operacional

• Tools costs.ts: summary, by-agent, by-model, by-provider, by-project, finance, budgets (12 tools)
• Tools activity.ts: company activity, issue activity, issue runs (4 tools)
• Tools skills.ts: list, get, files, create, import, delete (6 tools)
• Tools secrets.ts: list, providers, create, rotate, delete (5 tools)
• Tools: execution_workspaces (3 tools), adapters (2 tools), portability (2 tools)
• Tools company.ts (write): update, update_branding, members, update_member_permissions
• Heartbeat runs: list, live, get, events, log, cancel (6 tools)
• Testes de observabilidade

Critério de aceitação Sprint 4: get_cost_summary + get_budgets_overview retornam dados reais.

---

Sprint 5 — Plugins, Assets, Settings, Access

Objectivo: Gestão de plugins, assets, configuração e onboarding

• Tools plugins.ts: list, get, examples, tools, install, delete, enable, disable, upgrade, health, logs, config, dashboard, jobs, trigger (17 tools)
• Tools plugin_bridge.ts: execute_tool, bridge_data, bridge_action, ui_contributions (4 tools)
• Tools assets.ts: upload_image, upload_logo, get_content (3 tools) — suporte multipart/form-data no client
• Tools settings.ts: get/update general, get/update experimental (4 tools)
• Tools access.ts: create_invite, get_invite, get_onboarding, accept_invite, revoke_invite, list_join_requests, approve_join_request (7 tools)
• Testes de plugins e settings

Critério de aceitação Sprint 5: list_plugins + install_plugin + get_plugin_health funcionais.

---

Sprint 6 — Gateway Deploy + CI/CD + Documentação

Objectivo: Deploy produção + cobertura total

• Deploy no gateway (5.9.90.69) via PM2
• Registar porta 3175 no port-map.json do gateway
• CI/CD workflow Gitea (.gitea/workflows/deploy.yml)
• Actualizar ~/.claude/_resources/mcps.json
• Actualizar QR-Servidores.md com novo MCP
• docs/API_REFERENCE.md completo
• Testes integração end-to-end (todas as 159 tools)
• Smoke test final: workflow completo via gateway StreamableHTTP

Critério de aceitação Sprint 6: Todas as 159 tools operacionais via STDIO + StreamableHTTP + SSE. CI verde.

---

Critérios de Qualidade (pré-entrega)

[ ] Zero erros ESLint
[ ] Testes passam: npm run test
[ ] Build sem erros: npm run build
[ ] Capabilities completas (tools + resources + prompts)
[ ] Nomenclatura snake_case em todas as tools
[ ] Triple transport funcional (STDIO + StreamableHTTP + SSE na porta 3175)
[ ] Stateless (sessionIdGenerator: undefined)
[ ] Logger para stderr (nunca stdout em STDIO mode)
[ ] .env.example sem valores reais
[ ] CHANGELOG.md iniciado
[ ] CI verde no Gitea
[ ] 159 tools operacionais

---

Dependências

{
  "dependencies": {
    "@modelcontextprotocol/sdk": "^1.10.0",
    "dotenv": "^16.4.7",
    "winston": "^3.17.0",
    "zod": "^3.24.0"
  },
  "devDependencies": {
    "@types/node": "^22.0.0",
    "@typescript-eslint/eslint-plugin": "^7.18.0",
    "@typescript-eslint/parser": "^7.18.0",
    "eslint": "^8.57.1",
    "jest": "^30.0.5",
    "prettier": "^3.6.2",
    "ts-jest": "^29.4.0",
    "typescript": "^5.3.3"
  }
}

---

Notas de Implementação

1. PAPERCLIP_COMPANY_ID como constante — injectar em todas as tools que precisam de :companyId, nunca expor como parâmetro obrigatório ao utilizador.

2. Erros da API Paperclip — mapear para mensagens claras:

   • 401/403 -> "Sem autorização. Verificar PAPERCLIP_API_KEY."
   • 404 -> "Recurso não encontrado: {id}"
   • 422 -> incluir erros de validação da resposta

3. get_org_chart — retorna JSON da hierarquia de agentes, não o SVG. Usar /companies/:id/org (JSON) e não /org.svg.

4. wakeup_agent — o Paperclip acorda agentes via heartbeat; útil para forçar execução de uma rotina ou atribuir uma issue urgente.

5. checkout_issue — permite ao Claude Code "reservar" uma issue enquanto trabalha nela, sinalizando que está em curso.

6. create_agent_hire — usa governance/approval workflow. Preferível a create_agent directo quando há supervisão activa.

7. Idempotência — create_agent com mesmo name pode criar duplicado. Adicionar verificação prévia com list_agents se necessário.

8. Costs — endpoints de custos aceitam query params from, to (ISO dates) para filtragem temporal.

9. Secrets — valores nunca são retornados em plain text. Apenas metadados (nome, provider, criação).

10. Attachments e Assets — uploads usam multipart/form-data. O client precisa de suportar este content-type para upload_issue_attachment, upload_image_asset e upload_company_logo.

11. Plugins — install_plugin aceita URL ou path para o plugin. execute_plugin_tool permite invocar tools expostas por plugins instalados.

12. Instance Settings — alterações a experimental podem activar/desactivar funcionalidades em beta. Usar com cautela.

13. Invites — create_invite gera token único para onboarding de novos agentes. O fluxo completo: create -> partilhar token -> accept.

14. Plugin Bridge — plugin_bridge_data e plugin_bridge_action permitem comunicação directa com plugins via data/action pattern.

---

SPEC criado em 07-04-2026 | Actualizado em 07-04-2026 (cobertura completa API v0.3.1) Baseado no PROC-MCP-Desenvolvimento.md v2.5 + análise directa do código-fonte Paperclip