@selfagency/beans-mcp 0.4.2 → 0.6.0

package/README.md

@@ -1,9 +1,13 @@
 # @selfagency/beans-mcp 🫘
 
-[![Test & Build](https://github.com/selfagency/beans-mcp/actions/workflows/test.yml/badge.svg)](https://github.com/selfagency/beans-mcp/actions/workflows/test.yml) [![codecov](https://codecov.io/gh/selfagency/beans-mcp/graph/badge.svg?token=udeAJyu8Nu)](https://codecov.io/gh/selfagency/beans-mcp)
+<img src="docs/assets/icon.png" alt="beans-mcp icon" width="300" />
+
+[![Test & Build](https://github.com/selfagency/beans-mcp/actions/workflows/test.yml/badge.svg)](https://github.com/selfagency/beans-mcp/actions/workflows/test.yml) [![codecov](https://codecov.io/gh/selfagency/beans-mcp/graph/badge.svg?token=udeAJyu8Nu)](https://codecov.io/gh/selfagency/beans-mcp) ![NPM Version](https://img.shields.io/npm/v/@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.
 
+Documentation: [beans-mcp.self.agency](https://beans-mcp.self.agency)
+
 > 🤖 **Try Beans fully-integrated with GitHub Copilot in VS Code! Install the <a href="https://marketplace.visualstudio.com/items?itemName=selfagency.beans-vscode">selfagency.beans-vscode</a> extension.**
 
 ## Usage
@@ -30,26 +34,44 @@ CLI version. If they differ, it prints a warning to stderr and continues startup
 
 ## 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
+| Tool                   | Description                                                                                                                                                                          |
+| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `beans_init`           | Initialize the workspace (optional `prefix`).                                                                                                                                        |
+| `beans_archive`        | Archive completed/scrapped beans.                                                                                                                                                    |
+| `beans_view`           | Fetch full bean details by `beanId` or `beanIds`.                                                                                                                                    |
+| `beans_create`         | Create a new bean (title/type + optional body/parent).                                                                                                                               |
+| `beans_bulk_create`    | Create multiple beans in one call, optionally under a shared parent.                                                                                                                 |
+| `beans_update`         | Consolidated metadata + body updates (status/type/priority/parent/clearParent/blocking/blockedBy/body/bodyAppend/bodyReplace) plus optional optimistic concurrency hint (`ifMatch`). |
+| `beans_bulk_update`    | Update multiple beans in one call, optionally reassigning them to a shared parent.                                                                                                   |
+| `beans_complete_tasks` | Mark all markdown checklist tasks within a bean as complete.                                                                                                                         |
+| `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 operations, with GraphQL passthrough.                                                                                                          |
+| `beans_bean_file`      | Read/edit/create/delete files under `.beans`.                                                                                                                                        |
+| `beans_output`         | Read extension output logs or show guidance.                                                                                                                                         |
+
+<details>
+<summary>Notes</summary>
 
 - 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.
+- 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.
-- Version mismatches are warning-only and non-blocking by design.
+- `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\`?`.
+
+</details>
 
 ## Examples
 
-### beans_init
+<details>
+<summary>beans_init</summary>
 
 Request:
 
@@ -63,7 +85,10 @@ Response (structuredContent):
 { "initialized": true }
 ```
 
-### beans_view
+</details>
+
+<details>
+<summary>beans_view</summary>
 
 Request:
 
@@ -94,7 +119,27 @@ Response (structuredContent):
 }
 ```
 
-### beans_create
+</details>
+
+<details>
+<summary>beans_archive</summary>
+
+Request:
+
+```json
+{}
+```
+
+Response (example):
+
+```json
+{ "archived": true, "archivedCount": 3 }
+```
+
+</details>
+
+<details>
+<summary>beans_create</summary>
 
 Request:
 
@@ -104,10 +149,13 @@ Request:
   "type": "feature",
   "status": "todo",
   "priority": "normal",
-  "description": "Implement theme toggle and styles"
+  "body": "Implement theme toggle and styles",
+  "parent": "epic-123"
 }
 ```
 
+> `description` is accepted as a deprecated alias for `body`.
+
 Response (structuredContent):
 
 ```json
@@ -121,7 +169,80 @@ Response (structuredContent):
 }
 ```
 
-### beans_update
+</details>
+
+<details>
+<summary>beans_bulk_create</summary>
+
+Request:
+
+```json
+{
+  "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):
+
+```json
+{
+  "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" } }
+  ]
+}
+```
+
+</details>
+
+<details>
+<summary>beans_bulk_update</summary>
+
+Request (move a batch of tasks to in-progress and assign them to a parent):
+
+```json
+{
+  "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):
+
+```json
+{
+  "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.
+
+</details>
+
+<details>
+<summary>beans_update</summary>
 
 Request (change status and add blocking):
 
@@ -161,7 +282,10 @@ Response (structuredContent):
 }
 ```
 
-### beans_delete
+</details>
+
+<details>
+<summary>beans_delete</summary>
 
 Request:
 
@@ -195,7 +319,10 @@ Batch response (summary):
 }
 ```
 
-### beans_reopen
+</details>
+
+<details>
+<summary>beans_reopen</summary>
 
 Request:
 
@@ -213,7 +340,35 @@ Response:
 { "bean": { "id": "bean-closed", "status": "todo" } }
 ```
 
-### beans_query — examples
+</details>
+
+<details>
+<summary>beans_complete_tasks</summary>
+
+Request:
+
+```json
+{ "beanId": "bean-abc" }
+```
+
+Response:
+
+```json
+{
+  "bean": {
+    "id": "bean-abc",
+    "status": "todo"
+  },
+  "totalTaskCount": 5,
+  "updatedTaskCount": 3,
+  "unchangedTaskCount": 2
+}
+```
+
+</details>
+
+<details>
+<summary>beans_query examples</summary>
 
 Refresh (list all beans):
 
@@ -272,7 +427,29 @@ Response (structuredContent):
 }
 ```
 
-### beans_bean_file
+Raw GraphQL passthrough (CLI parity with `beans query`):
+
+```json
+{
+  "operation": "graphql",
+  "graphql": "{ beans(filter: { type: [\"bug\"] }) { id title status } }"
+}
+```
+
+With variables:
+
+```json
+{
+  "operation": "graphql",
+  "graphql": "query($q: String!) { beans(filter: { search: $q }) { id title } }",
+  "variables": { "q": "authentication" }
+}
+```
+
+</details>
+
+<details>
+<summary>beans_bean_file</summary>
 
 Request (read):
 
@@ -289,7 +466,39 @@ Response:
 }
 ```
 
-### beans_output
+Request (atomic frontmatter update):
+
+```json
+{
+  "operation": "update_frontmatter",
+  "path": "beans-vscode-123--title.md",
+  "fields": {
+    "status": "in-progress",
+    "pr": "123",
+    "branch": "feature/cascade-status-and-skills-npm"
+  }
+}
+```
+
+Response:
+
+```json
+{
+  "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"
+  }
+}
+```
+
+</details>
+
+<details>
+<summary>beans_output</summary>
 
 Request (read last 200 lines):
 
@@ -307,6 +516,8 @@ Response:
 }
 ```
 
+</details>
+
 ## Programmatic usage
 
 ### Installation
@@ -318,11 +529,11 @@ npm install beans-mcp
 ### Example
 
 ```typescript
-import { createBeansMcpServer, parseCliArgs } from "@selfagency/beans-mcp";
+import { createBeansMcpServer, parseCliArgs } from '@selfagency/beans-mcp';
 
 const server = await createBeansMcpServer({
-  workspaceRoot: "/path/to/workspace",
-  cliPath: "beans", // or path to beans CLI
+  workspaceRoot: '/path/to/workspace',
+  cliPath: 'beans', // or path to beans CLI
 });
 
 // Connect to stdio transport or your own transport
@@ -359,6 +570,19 @@ CLI-compatible entrypoint for launching the server.
 
 Export of GraphQL schema, Zod validation schemas, and TypeScript types for Beans records and operations.
 
+## Agent Skills (`skills-npm`, `skills.sh`)
+
+This package ships a built-in Agent Skill under `skills/` and also publishes that skill in a format that fits the broader open skills ecosystem surfaced by [skills.sh](https://skills.sh/).
+
+- Skill path in package: `skills/beans-mcp/SKILL.md`
+- Published skill artifact: `https://beans-mcp.self.agency/.well-known/agent-skills/beans-mcp/SKILL.md`
+- Published discovery index: `https://beans-mcp.self.agency/.well-known/agent-skills/index.json`
+- Compatible with discovery tools that scan: `node_modules/**/skills/*/SKILL.md`
+
+That means you can use it with npm-based workflows such as `skills-npm`, while also pointing ecosystem tooling at the published skill artifact and discovery index used by skills catalogs like `skills.sh`.
+
+To symlink installed npm-packaged skills into your agent workspace, you can use `skills-npm` in your consuming project.
+
 ## License
 
 MIT