@selfagency/beans-mcp 🫘

MCP (Model Context Protocol) Server für den Beans Issue-Tracker. Bietet programmatische und CLI-Schnittstellen für KI-gestützte Interaktionen mit Beans-Workspaces.

Dokumentation: beans-mcp.self.agency

🤖 Testen Sie Beans vollständig integriert mit GitHub Copilot in VS Code! Installieren Sie die selfagency.beans-vscode Erweiterung.

Verwendung

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

Versionierung

@selfagency/beans-mcp hat eine eigene Paketversionierung. Die Kompatibilität mit der Beans CLI wird separat verfolgt.

Beim Start vergleicht der Server die installierte beans CLI-Version mit der hartcodierten unterstützten Beans-Version: 0.4.2. Wenn sie abweichen, wird eine Warnung auf stderr ausgegeben und der Start fortgesetzt.

Parameter

• --workspace-root oder Positionsargument: Pfad zum Workspace-Root

• --cli-path: Pfad zur Beans CLI

• --port: MCP-Server-Port (Standard: 39173)

• --log-dir: Log-Verzeichnis

• -h, --help: Verwendung anzeigen und beenden

Related MCP server: jira-cli-mcp

Zusammenfassung der öffentlichen MCP-Tools

• Das beans_query-Tool ist bewusst breit gefasst: Bevorzugen Sie es zum Auflisten, Suchen, Filtern oder Sortieren von Beans sowie zum Generieren von Copilot-Anweisungen (operation: 'llm_context').

• Alle Datei- und Log-Operationen validieren Pfade, um sie innerhalb des Workspace oder des VS Code-Log-Verzeichnisses zu halten. Das Präfix .beans/ wird automatisch von Pfaden entfernt – Sie können entweder some-bean.md oder .beans/some-bean.md übergeben, das Ergebnis ist dasselbe.

• beans_update ersetzt viele feingranulare Update-Tools; Aufrufer sollten es verwenden, um die öffentliche Tool-Oberfläche klein und vorhersagbar zu halten.

• beans_archive bietet CLI-Parität zum Archivieren abgeschlossener/verworfener Beans.

• Das Schließen eines Eltern-Beans über beans_update (status: completed oder status: scrapped) überträgt denselben Status auf alle Nachkommen.

• Das Wiederöffnen eines Eltern-Beans über beans_reopen überträgt den Zielstatus auf geschlossene Nachkommen (completed / scrapped).

• beans_bulk_create und beans_bulk_update arbeiten nach bestem Bemühen: Sie verarbeiten jedes Element sequentiell und geben ein Array mit Ergebnissen pro Element mit Erfolgs-/Fehlereinträgen zurück, anstatt atomar zu scheitern.

• Werte für title: im Frontmatter werden beim Schreiben automatisch in doppelte Anführungszeichen gesetzt. Übergeben Sie rohe Titel – die Anführungszeichen und das Escaping werden für Sie erledigt.

• beans_bean_file unterstützt update_frontmatter für atomare Frontmatter-Only-Schreibvorgänge; unterstützte Felder umfassen pr und branch.

• Ungefilterte Listenergebnisse werden mit einer kurzen Burst-TTL und einer Timestamp-Probe-Aktualisierungsstrategie zwischengespeichert. Mutationstools (beans_create, beans_update, beans_delete usw.) invalidieren den Cache sofort.

• Versionsabweichungen zwischen beans-mcp und der Beans CLI sind standardmäßig nur warnend und nicht blockierend.

• Wenn beanId in der Tool-Eingabe fehlt, enthalten Validierungsfehler einen Hinweis: Meinten Sie \beanId`?`.

Beispiele

Anfrage:

{ "prefix": "project" }

Antwort (structuredContent):

{ "initialized": true }

Anfrage:

{ "beanId": "bean-abc" }

Anfrage (mehrere Beans):

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

Antwort (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"
  }
}

Anfrage:

{}

Antwort (Beispiel):

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

Anfrage:

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

description wird als veralteter Alias für body akzeptiert.

Antwort (structuredContent):

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

Anfrage:

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

Das übergeordnete parent wird als Standard auf jedes Bean angewendet, das kein eigenes parent angibt. Hier werden Design mockups und Implement API epic-123 zugewiesen; Write tests überschreibt mit epic-456.

Antwort (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" } }
  ]
}

Anfrage (einen Batch von Aufgaben in Bearbeitung verschieben und einem Eltern zuweisen):

{
  "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" }
  ]
}

Antwort (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" } }
  ]
}

Beide Bulk-Tools arbeiten nach bestem Bemühen: Teilfehler werden pro Element gemeldet, anstatt den gesamten Batch abzubrechen.

Anfrage (Status ändern und Blockierung hinzufügen):

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

Anfrage (atomare Body-Änderungen):

{
  "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."
}

Hinweis: body (vollständiger Ersatz) kann nicht mit bodyAppend oder bodyReplace in derselben Anfrage kombiniert werden.

Antwort (structuredContent):

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

Anfrage:

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

Antwort:

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

Batch-Anfrage:

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

Batch-Antwort (Zusammenfassung):

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

Anfrage:

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

Antwort:

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

Anfrage:

{ "beanId": "bean-abc" }

Antwort:

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

Aktualisieren (alle Beans auflisten):

{ "operation": "refresh" }

Antwort (teilweise):

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

Filtern (Status/Typen/Tags):

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

Suche (Volltext):

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

Sortierung (Modi: status-priority-type-title, updated, created, id):

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

Bereit (nur bearbeitbare Beans):

{ "operation": "ready" }

LLM-Kontext (Copilot-Anweisungen generieren; optionales Schreiben in den Workspace):

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

Antwort (structuredContent):

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

Rohes GraphQL-Passthrough (CLI-Parität mit beans query):

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

Mit Variablen:

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

Anfrage (lesen):

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

Antwort:

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

Anfrage (atomares Frontmatter-Update):

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

Antwort:

{
  "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"
  }
}

Anfrage (letzte 200 Zeilen lesen):

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

Antwort:

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

Programmatische Verwendung

Installation

npm install beans-mcp

Beispiel

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)

Erstellt und initialisiert eine Beans MCP Server-Instanz.

Optionen:

• workspaceRoot (string): Pfad zum Beans-Workspace

• cliPath (string, optional): Pfad zur Beans-CLI-Executable (Standard: 'beans')

• name (string, optional): Servername (Standard: 'beans-mcp-server')

• version (string, optional): Serverversion

• logDir (string, optional): Verzeichnis für Server-Logs

• backend (BackendInterface, optional): Benutzerdefinierte Backend-Implementierung

Rückgabe: { server: McpServer; backend: BackendInterface }

startBeansMcpServer(argv)

CLI-kompatibler Einstiegspunkt zum Starten des Servers.

Hilfsfunktionen

• parseCliArgs(argv: string[]): CLI-Argumente parsen

• isPathWithinRoot(root: string, target: string): boolean: Prüfen, ob ein Pfad innerhalb des Root liegt

• sortBeans(beans, mode): Beans nach dem angegebenen Modus sortieren

Typen & Schemata

Export des GraphQL-Schemas, der Zod-Validierungsschemata und der TypeScript-Typen für Beans-Datensätze und -Operationen.

Agent Skills (skills-npm, skills.sh)

Dieses Paket enthält eine integrierte Agent Skill unter skills/ und veröffentlicht diese Skill auch in einem Format, das in das breitere Ökosystem der offenen Skills passt, das von skills.sh bereitgestellt wird.

• Skill-Pfad im Paket: skills/beans-mcp/SKILL.md

• Veröffentlichtes Skill-Artefakt: https://beans-mcp.self.agency/.well-known/agent-skills/beans-mcp/SKILL.md

• Veröffentlichter Discovery-Index: https://beans-mcp.self.agency/.well-known/agent-skills/index.json

• Kompatibel mit Discovery-Tools, die scannen: node_modules/**/skills/*/SKILL.md

Das bedeutet, Sie können es mit npm-basierten Workflows wie skills-npm verwenden und gleichzeitig Ökosystem-Tools auf das veröffentlichte Skill-Artefakt und den Discovery-Index verweisen, die von Skills-Katalogen wie skills.sh verwendet werden.

Um installierte npm-verpackte Skills in Ihren Agent-Workspace zu symbolisch verknüpfen, können Sie skills-npm in Ihrem konsumierenden Projekt verwenden.

Lizenz

MIT