@selfagency/beans-mcp 0.4.2 → 0.5.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +86 -12
- package/beans-mcp-server.cjs +451 -124
- package/index.cjs +451 -124
- package/index.d.ts +99 -0
- package/index.js +451 -124
- package/package.json +7 -6
package/README.md
CHANGED
|
@@ -30,22 +30,29 @@ CLI version. If they differ, it prints a warning to stderr and continues startup
|
|
|
30
30
|
|
|
31
31
|
## Summary of public MCP tools
|
|
32
32
|
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
33
|
+
| Tool | Description |
|
|
34
|
+
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
35
|
+
| `beans_init` | Initialize the workspace (optional `prefix`). |
|
|
36
|
+
| `beans_view` | Fetch full bean details by `beanId` or `beanIds`. |
|
|
37
|
+
| `beans_create` | Create a new bean (title/type + optional body/parent). |
|
|
38
|
+
| `beans_bulk_create` | Create multiple beans in one call, optionally under a shared parent. |
|
|
39
|
+
| `beans_update` | Consolidated metadata + body updates (status/type/priority/parent/clearParent/blocking/blockedBy/body/bodyAppend/bodyReplace) plus optional optimistic concurrency hint (`ifMatch`). |
|
|
40
|
+
| `beans_bulk_update` | Update multiple beans in one call, optionally reassigning them to a shared parent. |
|
|
41
|
+
| `beans_delete` | Delete one or many beans (`beanId` or `beanIds`, optional `force`). |
|
|
42
|
+
| `beans_reopen` | Reopen a completed or scrapped bean to an active status. |
|
|
43
|
+
| `beans_query` | Unified list/search/filter/sort/ready/llm_context/open_config operations. |
|
|
44
|
+
| `beans_bean_file` | Read/edit/create/delete files under `.beans`. |
|
|
45
|
+
| `beans_output` | Read extension output logs or show guidance. |
|
|
42
46
|
|
|
43
47
|
### Notes
|
|
44
48
|
|
|
45
49
|
- The `beans_query` tool is intentionally broad: prefer it for listing, searching, filtering or sorting beans, and for generating Copilot instructions (`operation: 'llm_context'`).
|
|
46
|
-
- All file and log operations validate paths to keep them within the workspace or the VS Code log directory.
|
|
50
|
+
- 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.
|
|
47
51
|
- `beans_update` replaces many fine-grained update tools; callers should use it to keep the public tool surface small and predictable.
|
|
48
|
-
-
|
|
52
|
+
- `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.
|
|
53
|
+
- Frontmatter `title:` values are automatically double-quoted on write. Pass raw titles — quoting and escaping is handled for you.
|
|
54
|
+
- 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.
|
|
55
|
+
- Version mismatches between `beans-mcp` and the Beans CLI are warning-only and non-blocking by design.
|
|
49
56
|
|
|
50
57
|
## Examples
|
|
51
58
|
|
|
@@ -104,10 +111,13 @@ Request:
|
|
|
104
111
|
"type": "feature",
|
|
105
112
|
"status": "todo",
|
|
106
113
|
"priority": "normal",
|
|
107
|
-
"
|
|
114
|
+
"body": "Implement theme toggle and styles",
|
|
115
|
+
"parent": "epic-123"
|
|
108
116
|
}
|
|
109
117
|
```
|
|
110
118
|
|
|
119
|
+
> `description` is accepted as a deprecated alias for `body`.
|
|
120
|
+
|
|
111
121
|
Response (structuredContent):
|
|
112
122
|
|
|
113
123
|
```json
|
|
@@ -121,6 +131,70 @@ Response (structuredContent):
|
|
|
121
131
|
}
|
|
122
132
|
```
|
|
123
133
|
|
|
134
|
+
### beans_bulk_create
|
|
135
|
+
|
|
136
|
+
Request:
|
|
137
|
+
|
|
138
|
+
```json
|
|
139
|
+
{
|
|
140
|
+
"parent": "epic-123",
|
|
141
|
+
"beans": [
|
|
142
|
+
{ "title": "Design mockups", "type": "task" },
|
|
143
|
+
{ "title": "Implement API", "type": "task", "priority": "high" },
|
|
144
|
+
{ "title": "Write tests", "type": "task", "parent": "epic-456" }
|
|
145
|
+
]
|
|
146
|
+
}
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
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`.
|
|
150
|
+
|
|
151
|
+
Response (structuredContent):
|
|
152
|
+
|
|
153
|
+
```json
|
|
154
|
+
{
|
|
155
|
+
"requestedCount": 3,
|
|
156
|
+
"successCount": 3,
|
|
157
|
+
"failedCount": 0,
|
|
158
|
+
"results": [
|
|
159
|
+
{ "bean": { "id": "task-1", "title": "Design mockups" } },
|
|
160
|
+
{ "bean": { "id": "task-2", "title": "Implement API" } },
|
|
161
|
+
{ "bean": { "id": "task-3", "title": "Write tests" } }
|
|
162
|
+
]
|
|
163
|
+
}
|
|
164
|
+
```
|
|
165
|
+
|
|
166
|
+
### beans_bulk_update
|
|
167
|
+
|
|
168
|
+
Request (move a batch of tasks to in-progress and assign them to a parent):
|
|
169
|
+
|
|
170
|
+
```json
|
|
171
|
+
{
|
|
172
|
+
"parent": "epic-123",
|
|
173
|
+
"beans": [
|
|
174
|
+
{ "beanId": "task-1", "status": "in-progress" },
|
|
175
|
+
{ "beanId": "task-2", "status": "in-progress" },
|
|
176
|
+
{ "beanId": "task-3", "status": "in-progress", "parent": "epic-456" }
|
|
177
|
+
]
|
|
178
|
+
}
|
|
179
|
+
```
|
|
180
|
+
|
|
181
|
+
Response (structuredContent):
|
|
182
|
+
|
|
183
|
+
```json
|
|
184
|
+
{
|
|
185
|
+
"requestedCount": 3,
|
|
186
|
+
"successCount": 3,
|
|
187
|
+
"failedCount": 0,
|
|
188
|
+
"results": [
|
|
189
|
+
{ "beanId": "task-1", "bean": { "id": "task-1", "status": "in-progress" } },
|
|
190
|
+
{ "beanId": "task-2", "bean": { "id": "task-2", "status": "in-progress" } },
|
|
191
|
+
{ "beanId": "task-3", "bean": { "id": "task-3", "status": "in-progress" } }
|
|
192
|
+
]
|
|
193
|
+
}
|
|
194
|
+
```
|
|
195
|
+
|
|
196
|
+
> Both bulk tools are best-effort: partial failures are reported per-item rather than aborting the whole batch.
|
|
197
|
+
|
|
124
198
|
### beans_update
|
|
125
199
|
|
|
126
200
|
Request (change status and add blocking):
|