@selfagency/beans-mcp 🫘

Servidor MCP (Model Context Protocol) para el rastreador de incidencias Beans. Proporciona interfaces programáticas y de línea de comandos para interacciones basadas en IA con espacios de trabajo de Beans.

Documentación: beans-mcp.self.agency

🤖 ¡Prueba Beans totalmente integrado con GitHub Copilot en VS Code! Instala la extensión selfagency.beans-vscode.

Uso

npx @selfagency/beans-mcp /path/to/workspace

Versiones

@selfagency/beans-mcp tiene su propio versionado de paquetes. La compatibilidad con la CLI de Beans se rastrea por separado.

Al iniciar, el servidor compara la versión instalada de la CLI de beans con la versión compatible de Beans definida en el código: 0.4.2. Si difieren, imprime una advertencia en stderr y continúa el inicio.

Parámetros

• --workspace-root o argumento posicional: Ruta raíz del espacio de trabajo

• --cli-path: Ruta a la CLI de Beans

• --port: Puerto del servidor MCP (por defecto: 39173)

• --log-dir: Directorio de registros

• -h, --help: Imprime el uso y sale

Related MCP server: jira-cli-mcp

Resumen de herramientas MCP públicas

• La herramienta beans_query es intencionadamente amplia: prefierela para listar, buscar, filtrar u ordenar beans, y para generar instrucciones de Copilot (operation: 'llm_context').

• Todas las operaciones con archivos y registros validan las rutas para mantenerlas dentro del espacio de trabajo o del directorio de registros de VS Code. El prefijo .beans/ se elimina automáticamente de las rutas — puedes pasar some-bean.md o .beans/some-bean.md y el resultado es el mismo.

• beans_update reemplaza muchas herramientas de actualización específicas; los llamadores deben usarla para mantener la superficie de herramientas públicas pequeña y predecible.

• beans_archive proporciona paridad con la CLI para archivar beans completados/descartados.

• Cerrar un bean padre mediante beans_update (status: completed o status: scrapped) propaga el mismo estado a todos los descendientes.

• Reabrir un bean padre mediante beans_reopen propaga el estado objetivo a los descendientes cerrados (completed / scrapped).

• beans_bulk_create y beans_bulk_update son de mejor esfuerzo: procesan cada elemento secuencialmente y devuelven un array de resultados por elemento con entradas de éxito/error en lugar de fallar atómicamente.

• Los valores de title: en el frontmatter se entrecomillan automáticamente al escribir. Pasa títulos sin procesar — el entrecomillado y escape se manejan por ti.

• beans_bean_file admite update_frontmatter para escrituras atómicas solo de frontmatter; los campos admitidos incluyen pr y branch.

• Los resultados de listas sin filtro se almacenan en caché con un TTL de ráfaga corta y una estrategia de actualización por sondeo de marca de tiempo. Las herramientas de mutación (beans_create, beans_update, beans_delete, etc.) invalidan la caché inmediatamente.

• Las discrepancias de versión entre beans-mcp y la CLI de Beans son solo advertencias y no bloquean por diseño.

• Cuando falta beanId en la entrada de la herramienta, los errores de validación incluyen una pista: ¿Quisiste decir \beanId`?`.

Ejemplos

Solicitud:

{ "prefix": "project" }

Respuesta (structuredContent):

{ "initialized": true }

Solicitud:

{ "beanId": "bean-abc" }

Solicitud (múltiples beans):

{ "beanIds": ["bean-abc", "bean-def"] }

Respuesta (structuredContent):

{
  "bean": {
    "id": "bean-abc",
    "title": "Fix login timeout",
    "status": "todo",
    "type": "bug",
    "priority": "critical",
    "body": "...markdown...",
    "createdAt": "2025-12-01T12:00:00Z",
    "updatedAt": "2025-12-02T08:00:00Z"
  }
}

Solicitud:

{}

Respuesta (ejemplo):

{ "archived": true, "archivedCount": 3 }

Solicitud:

{
  "title": "Add dark mode",
  "type": "feature",
  "status": "todo",
  "priority": "normal",
  "body": "Implement theme toggle and styles",
  "parent": "epic-123"
}

description se acepta como un alias obsoleto de body.

Respuesta (structuredContent):

{
  "bean": {
    "id": "new-1",
    "title": "Add dark mode",
    "status": "todo",
    "type": "feature"
  }
}

Solicitud:

{
  "parent": "epic-123",
  "beans": [
    { "title": "Design mockups", "type": "task" },
    { "title": "Implement API", "type": "task", "priority": "high" },
    { "title": "Write tests", "type": "task", "parent": "epic-456" }
  ]
}

El parent de nivel superior se aplica como valor predeterminado a cualquier bean que no especifique su propio parent. Aquí Design mockups e Implement API se asignan a epic-123; Write tests lo reemplaza con epic-456.

Respuesta (structuredContent):

{
  "requestedCount": 3,
  "successCount": 3,
  "failedCount": 0,
  "results": [
    { "bean": { "id": "task-1", "title": "Design mockups" } },
    { "bean": { "id": "task-2", "title": "Implement API" } },
    { "bean": { "id": "task-3", "title": "Write tests" } }
  ]
}

Solicitud (mover un lote de tareas a en progreso y asignarlas a un padre):

{
  "parent": "epic-123",
  "beans": [
    { "beanId": "task-1", "status": "in-progress" },
    { "beanId": "task-2", "status": "in-progress" },
    { "beanId": "task-3", "status": "in-progress", "parent": "epic-456" }
  ]
}

Respuesta (structuredContent):

{
  "requestedCount": 3,
  "successCount": 3,
  "failedCount": 0,
  "results": [
    { "beanId": "task-1", "bean": { "id": "task-1", "status": "in-progress" } },
    { "beanId": "task-2", "bean": { "id": "task-2", "status": "in-progress" } },
    { "beanId": "task-3", "bean": { "id": "task-3", "status": "in-progress" } }
  ]
}

Ambas herramientas masivas son de mejor esfuerzo: los fallos parciales se informan por elemento en lugar de abortar todo el lote.

Solicitud (cambiar estado y añadir bloqueo):

{
  "beanId": "bean-abc",
  "status": "in-progress",
  "blocking": ["bean-def"],
  "ifMatch": "etag-value"
}

Solicitud (modificaciones atómicas del cuerpo):

{
  "beanId": "bean-abc",
  "bodyReplace": [
    { "old": "- [ ] Task 1", "new": "- [x] Task 1" },
    { "old": "- [ ] Task 2", "new": "- [x] Task 2" }
  ],
  "bodyAppend": "## Summary\n\nAll checklist items completed."
}

Nota: body (reemplazo completo) no se puede combinar con bodyAppend o bodyReplace en la misma solicitud.

Respuesta (structuredContent):

{
  "bean": {
    "id": "bean-abc",
    "status": "in-progress",
    "blockingIds": ["bean-def"]
  }
}

Solicitud:

{ "beanId": "bean-old", "force": false }

Respuesta:

{ "deleted": true, "beanId": "bean-old" }

Solicitud por lotes:

{ "beanIds": ["bean-old", "bean-older"], "force": false }

Respuesta por lotes (resumen):

{
  "requestedCount": 2,
  "deletedCount": 2,
  "failedCount": 0,
  "results": [
    { "beanId": "bean-old", "deleted": true },
    { "beanId": "bean-older", "deleted": true }
  ]
}

Solicitud:

{
  "beanId": "bean-closed",
  "requiredCurrentStatus": "completed",
  "targetStatus": "todo"
}

Respuesta:

{ "bean": { "id": "bean-closed", "status": "todo" } }

Solicitud:

{ "beanId": "bean-abc" }

Respuesta:

{
  "bean": {
    "id": "bean-abc",
    "status": "todo"
  },
  "totalTaskCount": 5,
  "updatedTaskCount": 3,
  "unchangedTaskCount": 2
}

Actualizar (listar todos los beans):

{ "operation": "refresh" }

Respuesta (parcial):

{ "count": 12, "beans": [] }

Filtrar (estados/tipos/etiquetas):

{
  "operation": "filter",
  "statuses": ["in-progress", "todo"],
  "types": ["bug", "feature"],
  "tags": ["auth"]
}

Buscar (texto completo):

{ "operation": "search", "search": "authentication", "includeClosed": false }

Ordenar (modos: status-priority-type-title, updated, created, id):

{ "operation": "sort", "mode": "updated" }

Listos (solo beans accionables):

{ "operation": "ready" }

Contexto LLM (generar instrucciones de Copilot; escritura opcional al espacio de trabajo):

{ "operation": "llm_context", "writeToWorkspaceInstructions": true }

Respuesta (structuredContent):

{
  "graphqlSchema": "...",
  "generatedInstructions": "...",
  "instructionsPath": "/workspace/.github/instructions/beans-prime.instructions.md"
}

Paso directo de GraphQL sin procesar (paridad con CLI mediante beans query):

{
  "operation": "graphql",
  "graphql": "{ beans(filter: { type: [\"bug\"] }) { id title status } }"
}

Con variables:

{
  "operation": "graphql",
  "graphql": "query($q: String!) { beans(filter: { search: $q }) { id title } }",
  "variables": { "q": "authentication" }
}

Solicitud (lectura):

{ "operation": "read", "path": "beans-vscode-123--title.md" }

Respuesta:

{
  "path": "/workspace/.beans/beans-vscode-123--title.md",
  "content": "---\n...frontmatter...\n---\n# Title\n"
}

Solicitud (actualización atómica de frontmatter):

{
  "operation": "update_frontmatter",
  "path": "beans-vscode-123--title.md",
  "fields": {
    "status": "in-progress",
    "pr": "123",
    "branch": "feature/cascade-status-and-skills-npm"
  }
}

Respuesta:

{
  "path": "/workspace/.beans/beans-vscode-123--title.md",
  "bytes": 256,
  "updatedFields": ["status", "pr", "branch"],
  "frontmatter": {
    "status": "in-progress",
    "pr": "123",
    "branch": "feature/cascade-status-and-skills-npm"
  }
}

Solicitud (leer las últimas 200 líneas):

{ "operation": "read", "lines": 200 }

Respuesta:

{
  "path": "/workspace/.vscode/logs/beans-output.log",
  "content": "...log lines...",
  "linesReturned": 200
}

Uso programático

Instalación

npm install beans-mcp

Ejemplo

import { createBeansMcpServer, parseCliArgs } from '@selfagency/beans-mcp';

const server = await createBeansMcpServer({
  workspaceRoot: '/path/to/workspace',
  cliPath: 'beans', // or path to beans CLI
});

// Connect to stdio transport or your own transport

API

createBeansMcpServer(opts)

Crea e inicializa una instancia del servidor Beans MCP.

Opciones:

• workspaceRoot (string): Ruta al espacio de trabajo de Beans

• cliPath (string, opcional): Ruta al ejecutable de la CLI de Beans (por defecto: 'beans')

• name (string, opcional): Nombre del servidor (por defecto: 'beans-mcp-server')

• version (string, opcional): Versión del servidor

• logDir (string, opcional): Directorio para los registros del servidor

• backend (BackendInterface, opcional): Implementación personalizada del backend

Devuelve: { server: McpServer; backend: BackendInterface }

startBeansMcpServer(argv)

Punto de entrada compatible con CLI para iniciar el servidor.

Funciones de utilidad

• parseCliArgs(argv: string[]): Analiza argumentos de CLI

• isPathWithinRoot(root: string, target: string): boolean: Comprueba si una ruta está contenida dentro de la raíz

• sortBeans(beans, mode): Ordena beans según el modo especificado

Tipos y esquemas

Exportación del esquema GraphQL, esquemas de validación Zod y tipos TypeScript para registros y operaciones de Beans.

Habilidades de agente (skills-npm, skills.sh)

Este paquete incluye una habilidad de agente incorporada en skills/ y también publica esa habilidad en un formato que encaja en el ecosistema más amplio de habilidades abiertas expuesto por skills.sh.

• Ruta de la habilidad en el paquete: skills/beans-mcp/SKILL.md

• Artefacto de habilidad publicado: https://beans-mcp.self.agency/.well-known/agent-skills/beans-mcp/SKILL.md

• Índice de descubrimiento publicado: https://beans-mcp.self.agency/.well-known/agent-skills/index.json

• Compatible con herramientas de descubrimiento que escanean: node_modules/**/skills/*/SKILL.md

Esto significa que puedes usarlo con flujos de trabajo basados en npm como skills-npm, mientras también apuntas las herramientas del ecosistema al artefacto de habilidad publicado y al índice de descubrimiento utilizados por catálogos de habilidades como skills.sh.

Para enlazar simbólicamente las habilidades empaquetadas de npm instaladas en tu espacio de trabajo de agente, puedes usar skills-npm en tu proyecto consumidor.

Licencia

MIT