orquestra-mcp

Servidor MCP (Model Context Protocol) para Orquestra. Expone 89 tools que llaman a la API de orquestra-infra: lectura de contexto/dashboard/ workspace/infra/paridad/listados, escritura de tareas/ideas/changelog/ notas/docs/módulos/flujo/categorías/infra/proyectos, y corridas de QA — un agente puede prácticamente todo lo que un humano hace en la web, directo desde la conversación. get_setup_guide documenta el orden recomendado para configurar/sincronizar un proyecto completo sin crear duplicados.

Ver CLAUDE.md para contexto de desarrollo. Ver la memoria del proyecto orquestra-mcp-api-plan para las 8 fases del plan MCP/API completo.

Setup rápido (recomendado)

npm install
node bin/orquestra-mcp.mjs setup

Esto abre tu navegador en https://app.orquestra.me/cli-auth para confirmar tu sesión (Google o email/password, lo que ya uses) y:

• Si no tienes workspace/proyecto todavía: te crea uno default ("Mi primer proyecto", con los 6 estatus base) — puedes renombrarlo o cambiarlo cuando quieras desde orquestra-web.
• Si ya tienes uno o varios: te deja elegir cuál usar por default desde la misma terminal.

Guarda todo (apiToken, workspaceId, defaultProjectId) en ~/.orquestra/mcp-config.json — después de esto, node bin/orquestra-mcp.mjs (sin más flags ni env vars) ya funciona.

Variable opcional ORQUESTRA_WEB_URL para apuntar el login a otro lugar (ej. http://localhost:5173 mientras desarrollas orquestra-web local en vez de contra producción).

Setup manual (alternativa, sin el flujo de navegador)

Si preferís generar el token vos mismo en vez de usar setup:

1. Cuenta + workspace en orquestra-web: entra a la app, si no tienes workspaceId te manda al wizard de onboarding.

2. Token de servicio, con esa misma sesión ya logueada:

   curl -X POST "$API_BASE/v1/tokens" \
     -H "Authorization: Bearer $FIREBASE_ID_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"workspaceId":"<workspace-id>"}'

   El token se muestra una sola vez — guárdalo.

3. Pasa ORQUESTRA_API_TOKEN/ORQUESTRA_WORKSPACE_ID como env vars (ver abajo) — en este modo projectId es obligatorio en cada tool call, ya que no hay defaultProjectId guardado.

Configuración

Variables de entorno (todas opcionales si ya corriste setup — se leen de ~/.orquestra/mcp-config.json como fallback):

| Variable | Requerida sin setup | Default | |---|---|---| | ORQUESTRA_API_TOKEN | sí | — | | ORQUESTRA_WORKSPACE_ID | sí | — | | ORQUESTRA_DEFAULT_PROJECT_ID | no | — | | ORQUESTRA_API_BASE | no | ApiBaseUrl de producción | | ORQUESTRA_WEB_URL (solo setup) | no | https://app.orquestra.me |

Claude Code

Si ya corriste setup, alcanza con:

claude mcp add orquestra -- node /ruta/absoluta/a/orquestra-mcp/bin/orquestra-mcp.mjs

O manual, sin setup:

claude mcp add orquestra \
  -e ORQUESTRA_API_TOKEN=orq_... \
  -e ORQUESTRA_WORKSPACE_ID=... \
  -- node /ruta/absoluta/a/orquestra-mcp/bin/orquestra-mcp.mjs

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "orquestra": {
      "command": "node",
      "args": ["/ruta/absoluta/a/orquestra-mcp/bin/orquestra-mcp.mjs"]
    }
  }
}

(sin env si ya corriste setup; si no, agrega ORQUESTRA_API_TOKEN/ORQUESTRA_WORKSPACE_ID igual que en Claude Code.)

Tools

Lectura de contexto:

| Tool | Args | Descripción | |---|---|---| | get_project_context | projectId? | Snapshot compacto del proyecto (fase, tareas abiertas/vencidas/bloqueadas, módulos, ideas, changelog reciente) | | list_tasks | projectId?, statusId? | Lista de tareas, filtro opcional por estatus | | search | projectId?, q | Búsqueda por texto en tareas/notas/ideas/docs | | get_dashboard_summary | projectId? | Hoy/vencidas/bloqueadas, salud de módulos, actividad reciente | | get_infra_status | projectId? | Servicios, entornos y distribuciones con conteos operational/degraded/down | | get_parity_summary | projectId? | Desfases de paridad multiplataforma (tasks y modules por separado) | | get_workspace_summary | — | Progreso agregado de todos los proyectos del workspace | | get_stage_playbook | stageId | Plantilla de módulo+tareas para una etapa (pre|build|post) — sin red | | get_platform_playbook | platform | Guía de referencia + checklist de publicación en tienda (ios|android) — sin red | | get_skills_catalog | — | Catálogo de Claude Skills de terceros recomendadas — sin red | | preview_skill | key? / sourceRepo?+sourcePath? | Trae el SKILL.md real de una skill de terceros, sin instalar nada | | install_skill | key? / sourceRepo?+sourcePath?, scope, confirmed | Descarga e instala una skill en .claude/skills/ — solo después de preview_skill + confirmación del usuario; además registra la instalación en Orquestra (best-effort) | | list_installed_skills | projectId? | Registros reales de skills instaladas en el proyecto (colección skills, no el catálogo) | | create_skill_install / update_skill_install | ver server.mjs | Self-report manual de una skill instalada a mano, fuera del flujo de install_skill | | get_setup_guide | — | Orden recomendado (flujo→categorías→infra→módulos→tareas→ideas→notas→changelog→docs) para configurar/sincronizar sin duplicar — sin red | | list_modules / list_statuses / list_categories / list_services / list_environments / list_distributions | projectId? | Lista completa de cada entidad — revísalos antes de create_* para no duplicar (patrón upsert) |

Creación (create_*) y edición (update_*) — mismo patrón en todos, solo crear/editar, sin delete_*:

| Entidad | Tools | Notas | |---|---|---| | Tareas | create_task, update_task | update_task incluye scope — úsalo para resolver desfases de paridad | | Ideas | create_idea | | | Changelog | create_changelog_entry | Estilo Keep a Changelog | | Notas | create_note | | | Docs | create_doc | | | Módulos | create_module, update_module | scope también editable | | Flujo (estatus) | create_status, update_status | nextIds define las transiciones válidas | | Categorías | create_category, update_category | | | Servicios | create_service, update_service | update_service para cambiar status tras un incidente | | Entornos | create_environment, update_environment | update_environment para reflejar un deploy | | Distribuciones | create_distribution, update_distribution | |

Compuestas:

| Tool | Args | Descripción | |---|---|---| | init_project | name, description?, phase?, projectType?, distributions?, categories? | Crea un proyecto nuevo en el workspace — categorías+distribuciones+flujo conectado en un paso | | apply_stage_playbook | stageId, moduleName?, includeDates? | Crea el módulo + todas las tareas de la plantilla de una etapa |

Los campos enum (type, priority, status, etc.) están fijos y documentados en el inputSchema de cada tool — el modelo los ve sin adivinar. Todo lo que se crea/edita aparece en vivo en orquestra-web, sin necesidad de refrescar.

projectId es opcional en todas las tools de proyecto si hay un defaultProjectId configurado (por setup o por ORQUESTRA_DEFAULT_PROJECT_ID) — si no hay ninguno de los dos, la tool devuelve error pidiendo uno explícito. get_workspace_summary e init_project no usan projectId en absoluto (operan a nivel workspace).

El workspaceId nunca es un argumento de las tools — viene fijo de la configuración, así el token de servicio no puede usarse fuera del workspace para el que se creó.

Probar localmente

npm install
ORQUESTRA_API_TOKEN=orq_... ORQUESTRA_WORKSPACE_ID=... \
  npx @modelcontextprotocol/inspector node bin/orquestra-mcp.mjs

Abre la UI del inspector y llama las tools contra un proyecto real.

Flujo recomendado para configurar/sincronizar un proyecto

Para que un agente pueda "barrer" un proyecto completo (llenar o actualizar todo sin crear duplicados), el patrón es:

1. Llamar get_setup_guide una vez al inicio de la conversación de setup.
2. Para cada sección, en el orden que indica la guía: listar lo existente (list_*/search), decidir por coincidencia de name/title/type si ya hay algo — update_* si sí, create_* si no.
3. Respetar el orden: flujo → categorías → infra → módulos → tareas → ideas → notas → changelog → docs — los módulos y tareas referencian ids (statusId, categoryId) que deben existir antes.

No hay ninguna tool que haga esto automáticamente de punta a punta — la guía orienta al agente, pero decidir qué contenido va en cada create/update sigue siendo criterio del agente y del humano.

Estado

89 tools: lectura (contexto, dashboard, workspace, infra, paridad, standup, sync report, setup guide, playbooks de etapa y de plataforma, catálogo de skills, search) + list_* de cada colección + creación/edición de tareas (con checklist, tiempo, adjuntos, merge), ideas (con comentarios), notas, docs, changelog (con corte de versión), módulos, flujo, categorías, infraestructura, proyecto, contenido (canales, campañas, contenido, Postproxy), agentes, skills y sugerencias + compuestas (init_project, apply_stage_playbook, apply_platform_playbook, install_skill). Sin delete_* salvo adjuntos e ítems de checklist. Publicado en npm como orquestra-mcp (unscoped) -- npx orquestra-mcp setup.