https://github.com/selfagency/beans-mcp
🫘 MCP server for Beans issue tracker
https://github.com/selfagency/beans-mcp
ai-agents beans issue-tracker issues issues-tracker mcp mcp-server model-context-protocol
Last synced: about 2 months ago
JSON representation
🫘 MCP server for Beans issue tracker
- Host: GitHub
- URL: https://github.com/selfagency/beans-mcp
- Owner: selfagency
- License: mit
- Created: 2026-02-25T00:06:43.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-03-13T20:02:00.000Z (3 months ago)
- Last Synced: 2026-03-14T07:52:47.827Z (3 months ago)
- Topics: ai-agents, beans, issue-tracker, issues, issues-tracker, mcp, mcp-server, model-context-protocol
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/@selfagency/beans-mcp
- Size: 381 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE.txt
Awesome Lists containing this project
README
# @selfagency/beans-mcp 🫘
[](https://github.com/selfagency/beans-mcp/actions/workflows/test.yml) [](https://codecov.io/gh/selfagency/beans-mcp)
MCP (Model Context Protocol) server for [Beans](https://github.com/hmans/beans) issue tracker. Provides programmatic and CLI interfaces for AI-powered interactions with Beans workspaces.
> 🤖 **Try Beans fully-integrated with GitHub Copilot in VS Code! Install the selfagency.beans-vscode extension.**
## Usage
```bash
npx @selfagency/beans-mcp /path/to/workspace
```
### Versioning
`@selfagency/beans-mcp` tracks upstream [Beans](https://github.com/hmans/beans) versions.
For example, Beans `v0.4.2` maps to `@selfagency/beans-mcp@0.4.2`.
At startup, the server compares its own package version against the installed `beans`
CLI version. 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
- `beans_init` — Initialize the workspace (optional `prefix`).
- `beans_view` — Fetch full bean details by `beanId` or `beanIds`.
- `beans_create` — Create a new bean (title/type + optional fields).
- `beans_update` — Consolidated metadata + body updates (status/type/priority/parent/clearParent/blocking/blockedBy/body/bodyAppend/bodyReplace) plus optional optimistic concurrency hint (`ifMatch`).
- `beans_delete` — Delete one or many beans (`beanId` or `beanIds`, optional `force`).
- `beans_reopen` — Reopen a completed or scrapped bean to an active status.
- `beans_query` — Unified list/search/filter/sort/ready/llm_context/open_config operations.
- `beans_bean_file` — Read/edit/create/delete files under `.beans`.
- `beans_output` — Read extension output logs or show guidance.
### 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.
- `beans_update` replaces many fine-grained update tools; callers should use it to keep the public tool surface small and predictable.
- Version mismatches are warning-only and non-blocking by design.
## Examples
### beans_init
Request:
```json
{ "prefix": "project" }
```
Response (structuredContent):
```json
{ "initialized": true }
```
### beans_view
Request:
```json
{ "beanId": "bean-abc" }
```
Request (multiple beans):
```json
{ "beanIds": ["bean-abc", "bean-def"] }
```
Response (structuredContent):
```json
{
"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_create
Request:
```json
{
"title": "Add dark mode",
"type": "feature",
"status": "todo",
"priority": "normal",
"description": "Implement theme toggle and styles"
}
```
Response (structuredContent):
```json
{
"bean": {
"id": "new-1",
"title": "Add dark mode",
"status": "todo",
"type": "feature"
}
}
```
### beans_update
Request (change status and add blocking):
```json
{
"beanId": "bean-abc",
"status": "in-progress",
"blocking": ["bean-def"],
"ifMatch": "etag-value"
}
```
Request (atomic body modifications):
```json
{
"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):
```json
{
"bean": {
"id": "bean-abc",
"status": "in-progress",
"blockingIds": ["bean-def"]
}
}
```
### beans_delete
Request:
```json
{ "beanId": "bean-old", "force": false }
```
Response:
```json
{ "deleted": true, "beanId": "bean-old" }
```
Batch request:
```json
{ "beanIds": ["bean-old", "bean-older"], "force": false }
```
Batch response (summary):
```json
{
"requestedCount": 2,
"deletedCount": 2,
"failedCount": 0,
"results": [
{ "beanId": "bean-old", "deleted": true },
{ "beanId": "bean-older", "deleted": true }
]
}
```
### beans_reopen
Request:
```json
{
"beanId": "bean-closed",
"requiredCurrentStatus": "completed",
"targetStatus": "todo"
}
```
Response:
```json
{ "bean": { "id": "bean-closed", "status": "todo" } }
```
### beans_query — examples
Refresh (list all beans):
```json
{ "operation": "refresh" }
```
Response (partial):
```json
{ "count": 12, "beans": [] }
```
Filter (statuses/types/tags):
```json
{
"operation": "filter",
"statuses": ["in-progress", "todo"],
"types": ["bug", "feature"],
"tags": ["auth"]
}
```
Search (full-text):
```json
{ "operation": "search", "search": "authentication", "includeClosed": false }
```
Sort (modes: `status-priority-type-title`, `updated`, `created`, `id`):
```json
{ "operation": "sort", "mode": "updated" }
```
Ready (actionable beans only):
```json
{ "operation": "ready" }
```
LLM context (generate Copilot instructions; optional write-to-workspace):
```json
{ "operation": "llm_context", "writeToWorkspaceInstructions": true }
```
Response (structuredContent):
```json
{
"graphqlSchema": "...",
"generatedInstructions": "...",
"instructionsPath": "/workspace/.github/instructions/beans-prime.instructions.md"
}
```
### beans_bean_file
Request (read):
```json
{ "operation": "read", "path": "beans-vscode-123--title.md" }
```
Response:
```json
{
"path": "/workspace/.beans/beans-vscode-123--title.md",
"content": "---\n...frontmatter...\n---\n# Title\n"
}
```
### beans_output
Request (read last 200 lines):
```json
{ "operation": "read", "lines": 200 }
```
Response:
```json
{
"path": "/workspace/.vscode/logs/beans-output.log",
"content": "...log lines...",
"linesReturned": 200
}
```
## Programmatic usage
### Installation
```bash
npm install beans-mcp
```
### Example
```typescript
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)
Creates and initializes a Beans MCP server instance.
**Options:**
- `workspaceRoot` (string): Path to the Beans workspace
- `cliPath` (string, optional): Path to Beans CLI executable (default: 'beans')
- `name` (string, optional): Server name (default: 'beans-mcp-server')
- `version` (string, optional): Server version
- `logDir` (string, optional): Directory for server logs
- `backend` (BackendInterface, optional): Custom backend implementation
**Returns:** `{ server: McpServer; backend: BackendInterface }`
#### startBeansMcpServer(argv)
CLI-compatible entrypoint for launching the server.
### Utility Functions
- `parseCliArgs(argv: string[])`: Parse CLI arguments
- `isPathWithinRoot(root: string, target: string): boolean`: Check if path is contained within root
- `sortBeans(beans, mode)`: Sort beans by specified mode
### Types & Schemas
Export of GraphQL schema, Zod validation schemas, and TypeScript types for Beans records and operations.
## License
MIT