Extensión MCP de Merlin Project

Acceso MCP de solo lectura a los documentos de proyecto abiertos en Merlin Project en tu Mac, empaquetado como una extensión de Claude Desktop (.mcpb).

Pregunta sobre tu plan, busca actividades, recursos, asignaciones, riesgos, incidencias y adjuntos, y obtén cifras de coste, trabajo o valor ganado en cualquier rango de fechas, sin salir de Merlin Project. La extensión solo lee: nunca cambia, guarda ni elimina nada en tus documentos. Tú eliges qué documento abierto puede ver Claude al inicio de cada chat, mediante el popover de acceso MCP en la barra de herramientas de Merlin Project.

Requisitos

• macOS

• Merlin Project instalado, en ejecución y con acceso MCP habilitado para el documento que quieres que Claude lea

• Node.js 18 o superior (Claude Desktop incluye su propio entorno de ejecución)

Related MCP server: OmniPlan MCP Server

Instalación

Compila el archivo de la extensión desde el código fuente y, a continuación, abre el MerlinProject.mcpb resultante con Claude Desktop, que te ofrecerá instalarlo:

npm install
npm run pack        # writes MerlinProject.mcpb

No es necesario que Merlin Project esté en ejecución cuando instales la extensión — Claude verá la lista completa de herramientas de todos modos, y se conecta a la aplicación en cuanto se lanza.

Cómo funciona

Merlin Project está en sandbox y ejecuta su servidor MCP dentro de la aplicación, escuchando en un socket de dominio Unix en su contenedor de App Group. Esta extensión es el puente entre ese socket y el transporte stdio que usa Claude Desktop:

Claude  ⇄  stdio  ⇄  extension server  ⇄  extension client (cached)  ⇄  socket  ⇄  Merlin Project

• tools/list / resources/list se responden localmente desde server/catalog.json, de modo que Claude ve los metadatos completos de las herramientas incluso cuando Merlin Project no está en ejecución.

• tools/call / resources/read se reenvían al servidor en vivo dentro de la aplicación a través del socket en ~/Library/Group Containers/9R6P9VZV27.net.projectwizards.merlinproject.mcp/mcp.sock (se puede sobrescribir mediante MERLIN_MCP_SOCKET, que aparece en Claude Desktop como el ajuste «Socket Path Override» de la extensión; déjalo vacío fuera de las pruebas). Debido a que sockaddr_un limita las rutas de socket a 104 bytes — límite que la ruta absoluta del contenedor supera con nombres de cuenta largos — el shim ejecuta chdir al contenedor y se conecta mediante el nombre de archivo relativo.

• Cuando Merlin Project no está disponible, las llamadas a herramientas devuelven un mensaje estructurado de «no en ejecución» que indica al agente que te pida lanzar la aplicación. La extensión reintenta la conexión en cada llamada, por lo que detecta la aplicación en ejecución en la siguiente solicitud, sin necesidad de reiniciar Claude. Deliberadamente, nunca lanza Merlin Project por sí sola.

• La extensión anuncia la identidad del servidor en vivo cuando Merlin Project está activo al inicio de la sesión, y reenvía el clientInfo real del agente durante el handshake del socket, de modo que el popover de herramientas conectadas de la aplicación muestra «Claude» en lugar de la extensión.

Las herramientas en sí — list_open_documents, set_current_document, get_schema_types, get_objects, find_objects, count_objects, list_related, get_media y get_time_phased_values — están implementadas dentro de Merlin Project, no aquí. Este repositorio contiene solo el puente.

Una compilación Swift del mismo puente se distribuye con Merlin Project para usarse fuera de Claude Desktop. Ambas son idénticas en comportamiento y se mantienen sincronizadas; los encabezados de archivo aquí nombran sus contrapartes Swift. A diferencia de la compilación Swift, esta no tiene entitlement de App Group y simplemente construye la ruta del contenedor directamente, lo que funciona para procesos sin sandbox.

Archivos

• manifest.json — manifiesto MCPB (server.type: "node").

• server/index.js — punto de entrada; servidor MCP con interfaz stdio.

• server/bridge.js — caché de conexiones, transporte por socket, lógica de reenvío.

• server/catalog.json — instantánea generada de tools/list / resources/list del servidor en vivo. No editar a mano.

• scripts/generate-catalog.js — regenera server/catalog.json a partir de una compilación en ejecución.

• scripts/test-e2e.js — pruebas de extremo a extremo (reenvío en vivo, respaldo con la aplicación detenida, recuperación a mitad de sesión).

Desarrollo

npm install                  # once, and after dependency changes
npm run generate-catalog     # after the app's tool metadata changes; needs Merlin Project running
npm test                     # phase A needs Merlin Project running; B and C are self-contained
npm run pack                 # builds MerlinProject.mcpb

Merlin Project en sí es la única fuente de verdad para los metadatos de herramientas y recursos: server/catalog.json se genera pidiendo a una aplicación en ejecución sus tools/list y resources/list y capturando las respuestas literalmente. Se incluye en el repositorio para que empaquetar la extensión no requiera una aplicación en ejecución. Regenera el archivo y vuelve a empaquetar cada vez que cambien los metadatos de herramientas de la aplicación.

Licencia

MIT — consulta LICENSE.