@selfagency/beans-mcp 0.1.4 → 0.5.0

package/README.md

@@ -12,6 +12,14 @@ MCP (Model Context Protocol) server for [Beans](https://github.com/hmans/beans)
 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
@@ -22,21 +30,29 @@ npx @selfagency/beans-mcp /path/to/workspace
 
 ## Summary of public MCP tools
 
-- `beans_init` — Initialize the workspace (optional `prefix`).
-- `beans_view` — Fetch full bean details by `beanId`.
-- `beans_create` — Create a new bean (title/type + optional fields).
-- `beans_update` — Consolidated metadata updates (status/type/priority/parent/clearParent/blocking/blockedBy).
-- `beans_delete` — Delete a bean (`beanId`, optional `force`).
-- `beans_reopen` — Reopen a completed or scrapped bean to an active status.
-- `beans_query` — Unified list/search/filter/sort/llm_context/open_config operations.
-- `beans_bean_file` — Read/edit/create/delete files under `.beans`.
-- `beans_output` — Read extension output logs or show guidance.
+| Tool                | Description                                                                                                                                                                          |
+| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `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 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_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.
+- 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_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.
+- 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.
 
 ## Examples
 
@@ -62,6 +78,12 @@ Request:
 { "beanId": "bean-abc" }
 ```
 
+Request (multiple beans):
+
+```json
+{ "beanIds": ["bean-abc", "bean-def"] }
+```
+
 Response (structuredContent):
 
 ```json
@@ -89,10 +111,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
@@ -106,6 +131,70 @@ Response (structuredContent):
 }
 ```
 
+### beans_bulk_create
+
+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" } }
+  ]
+}
+```
+
+### beans_bulk_update
+
+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.
+
 ### beans_update
 
 Request (change status and add blocking):
@@ -114,10 +203,26 @@ Request (change status and add blocking):
 {
   "beanId": "bean-abc",
   "status": "in-progress",
-  "blocking": ["bean-def"]
+  "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
@@ -144,6 +249,26 @@ Response:
 { "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:
@@ -199,6 +324,12 @@ Sort (modes: `status-priority-type-title`, `updated`, `created`, `id`):
 { "operation": "sort", "mode": "updated" }
 ```
 
+Ready (actionable beans only):
+
+```json
+{ "operation": "ready" }
+```
+
 LLM context (generate Copilot instructions; optional write-to-workspace):
 
 ```json
@@ -211,7 +342,7 @@ Response (structuredContent):
 {
   "graphqlSchema": "...",
   "generatedInstructions": "...",
-  "instructionsPath": "/workspace/.github/instructions/tasks.instructions.md"
+  "instructionsPath": "/workspace/.github/instructions/beans-prime.instructions.md"
 }
 ```