Beans MCP

@voxslopuli/beans-mcp 🫘

MCP (Model Context Protocol) server for Beans issue tracker. Provides programmatic and CLI interfaces for AI-powered interactions with Beans workspaces.

Documentation: beans-mcp.voxslopuli.org

🤖 Try Beans fully-integrated with GitHub Copilot in VS Code! Install the selfagency.beans-vscode extension.

Usage

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

Bundled beans CLI

The beans CLI binary is bundled via platform-specific optional dependencies (@voxslopuli/beans-cli-darwin-arm64, -darwin-x64, -linux-arm64, -linux-x64, -win32-x64), pinned to the supported Beans version (0.4.2). At startup the server resolves the bundled binary first and falls back to the beans command in PATH. An explicit --cli-path always wins.

To release new platform packages when Beans publishes a new version:

# 1. Bump beansCli.version + optionalDependencies in package.json

pnpm fetch-beans-binaries --version

2. Verify staged binaries in build/beans-cli/, then publish

pnpm publish-beans-cli # add --dry-run to preview

Or dispatch the Release beans CLI packages workflow on GitHub Actions.

Versioning

@voxslopuli/beans-mcp has its own package versioning. Compatibility with the Beans CLI is tracked separately.

At startup, the server compares the installed beans CLI version against the hardcoded supported Beans version: 0.4.2. If they differ, it prints a warning to stderr and continues startup.

Parameters

• --workspace-root or positional arg: Workspace root path
• --cli-path: Path to Beans CLI
• --port: MCP server port (default: 39173)
• --log-dir: Log directory
• -h, --help: Print usage and exit

Summary of public MCP tools

Notes

• The beans_query tool is intentionally broad: prefer it for listing, searching, filtering or sorting beans, and for generating Copilot instructions (operation: 'llm_context').
• All file and log operations validate paths to keep them within the workspace or the VS Code log directory. The .beans/ prefix is automatically stripped from paths — you can pass either some-bean.md or .beans/some-bean.md and the result is the same.
• beans_update replaces many fine-grained update tools; callers should use it to keep the public tool surface small and predictable.
• beans_archive provides CLI parity for archiving completed/scrapped beans.
• Closing a parent bean via beans_update (status: completed or status: scrapped) cascades the same status to all descendants.
• Reopening a parent bean via beans_reopen cascades the target status to closed descendants (completed / scrapped).
• beans_bulk_create and beans_bulk_update are best-effort: they process each item sequentially and return a per-item result array with success/error entries rather than failing atomically.
• Frontmatter title: values are automatically double-quoted on write. Pass raw titles — quoting and escaping is handled for you.
• beans_bean_file supports update_frontmatter for atomic frontmatter-only writes; supported fields include pr and branch.
• Unfiltered list results are cached with a short burst TTL and a timestamp-probe refresh strategy. Mutation tools (beans_create, beans_update, beans_delete, etc.) invalidate the cache immediately.
• Version mismatches between beans-mcp and the Beans CLI are warning-only and non-blocking by design.
• When beanId is missing in tool input, validation errors include a hint: Did you mean \beanId\?.

Examples

beans_init

Request:

{ "prefix": "project" }

Response (structuredContent):

{ "initialized": true }

beans_view

Request:

{ "beanId": "bean-abc" }

Request (multiple beans):

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

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

beans_archive

Request:

{}

Response (example):

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

beans_create

Request:

{

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

description is accepted as a deprecated alias for body.

Response (structuredContent):

{

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

beans_bulk_create

Request:

{

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

The top-level parent is applied as a default to any bean that does not specify its own parent. Here Design mockups and Implement API are assigned to epic-123; Write tests overrides with epic-456.

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

beans_bulk_update

Request (move a batch of tasks to in-progress and assign them to a parent):

{

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

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

Both bulk tools are best-effort: partial failures are reported per-item rather than aborting the whole batch.

beans_update

Request (change status and add blocking):

{

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

Request (atomic body modifications):

{

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

Note: body (full replacement) cannot be combined with bodyAppend or bodyReplace in the same request.

Response (structuredContent):

{

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

beans_delete

Request:

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

Response:

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

Batch request:

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

Batch response (summary):

{

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

beans_reopen

Request:

{

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

Response:

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

beans_complete_tasks

Request:

{ "beanId": "bean-abc" }

Response:

{

"bean": { "id"