@loopable/mcp 0.3.11 → 0.4.1

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.
Files changed (3) hide show
  1. package/README.md +31 -6
  2. package/lib/tools.mjs +409 -37
  3. package/package.json +1 -1
package/README.md CHANGED
@@ -15,8 +15,11 @@ for Claude Code; any other MCP host runs it the same way:
15
15
 
16
16
  Any studio member mints their own in Loopable, from the account menu under
17
17
  **My agent tokens**: it acts as them, and whatever their role, as a developer —
18
- it works the backlog and reports up to `in_review`, and it can never approve,
19
- change settings or decide what a client sees. A studio admin can also mint one
18
+ it works the backlog and moves any item to any status, and it can never approve,
19
+ change settings or decide what a client sees — unless they tick **Let it act
20
+ as my role** when minting it, which lends it their own studio role (still never
21
+ a client seat, a client conversation, a new token, or the approval of a draft a
22
+ token or the product owner proposed). A studio admin can also mint one
20
23
  for an agent member under **Settings → Tokens** — an account with no mailbox
21
24
  and no password, that can only ever act through a token — and sees and revokes
22
25
  everybody's there. Either way the secret is shown once, on the screen that
@@ -73,10 +76,30 @@ gets this server, and most of them do not have a token.
73
76
  | `revise` | correct an item's title or body |
74
77
  | `link_items` | say one item blocks another |
75
78
  | `write_brief` | the spec of one item — the ask, the acceptance criteria, what is out of scope. Written directly on a studio token, proposed on any other |
76
- | `report_progress` | move an item to todo / in_progress / in_review / blocked / awaiting_input. ready / verifying / done are a person's words: only a token its owner minted with the grant may set them, and only when that person asks and names the items |
79
+ | `report_progress` | move an item to any status — todo / ready / in_progress / in_review / verifying / done / blocked / awaiting_input / dropped — on your own judgement; the trail names you and the token. `ready` still needs the item to have nothing missing |
77
80
  | `open_session` | say you have started on an item — opens the live record of this piece of work |
78
81
  | `post_activity` | one line into an open session: thought, action, question, result or error |
79
82
  | `close_session` | end it — `error` takes a summary; `complete` is a claim and carries its evidence (brief revision, HEAD sha, verdict, every criterion, screenshots, cost, and optionally the pull request url — open it first, because a closed session is never updated again), and moves the item to `in_review` |
83
+ | `features` | create or edit a feature — only on a token minted to act as its holder's role; any other token is told to `propose` it |
84
+ | `record_decision` | record a decision, or supersede one with `supersedes_id` — admin and pm, so a full-role token of theirs |
85
+ | `raid` | the RAID register: list, create, update — every studio role writes it |
86
+ | `stakeholders` | the roster: list, create, update — admin and pm write |
87
+ | `commitments` | the ledger: list, create, update — admin and pm write |
88
+ | `evidence` | the signals: list, create, update, dismiss, restore — every studio role writes it |
89
+ | `environments` | where the project runs: list, create, update, delete, record a version — admin and pm write |
90
+ | `visibility` | the switches deciding which registers a client sees: get, set — admin and pm |
91
+ | `budgets` | the product owner's monthly caps and spend: get, set — admin and pm set |
92
+ | `po_config` | the product owner's profile, persona and foundation documents — admin and pm write |
93
+ | `studio_members` | the studio's members and their roles — studio settings, which no token reaches today |
94
+ | `invites` | invite, cancel, re-send an invitation — studio settings, which no token reaches today |
95
+ | `approval_queue` | read the queue: what is pending, and what was declined or withdrawn and why |
96
+
97
+ The family tools take an `action` and, for a write, the request body as
98
+ `fields`. Each is the browser's own route on the `/agent` side, with the same
99
+ need (`api/index.mjs`, `AGENT_TWINS`): a token acting as a developer reads and
100
+ meets the developer's 403 on an admin or pm write, and a token its holder
101
+ minted to act as their role writes as them — the registers included, directly,
102
+ with no draft in the approval queue.
80
103
 
81
104
  ## Starting work
82
105
 
@@ -119,9 +142,11 @@ open the session — and until it lands, doing it by hand in that order is the
119
142
  same thing.
120
143
 
121
144
  `ready_blockers` is the one field to read before anything else. A non-empty
122
- list means nobody has groomed the item — there is no criterion carrying a
123
- verify method, or the project has no registered environment — and it is not
124
- work to pick up yet.
145
+ list means nobody has groomed the item — no brief has been written, there is
146
+ no criterion carrying a verify method, or the project has no registered
147
+ environment — and it is not work to pick up yet. It is judged when you read a
148
+ `todo` or `ready` item, not only when the clock last groomed it, and while it
149
+ is not empty no agent token may move the item to `ready`.
125
150
 
126
151
  ## Which kind
127
152
 
package/lib/tools.mjs CHANGED
@@ -90,6 +90,392 @@ const withTitles = (edge, named) => ({
90
90
  to: named.get(nodeKey(edge.to_kind, edge.to_id)) ?? null,
91
91
  });
92
92
 
93
+ /*
94
+ * WHAT THE UI WRITES, ONE TOOL PER FAMILY (395).
95
+ *
96
+ * "I want all the privileges I have on the UI to be available for me here."
97
+ * Each family tool takes an `action` naming one route of its family and, for
98
+ * a write, the request body as `fields` — passed through as it is. The API
99
+ * holds the validation, the same as the graph tools' KIND_HELP argument: a
100
+ * copy of each register's field rules here would refuse a field the API had
101
+ * learned the day this package went a version out of date. A bad field comes
102
+ * back as the API's own 400, naming it.
103
+ *
104
+ * NO ROLE IS CHECKED HERE. The routes behind these are the browser's, with
105
+ * the browser's needs (api/index.mjs AGENT_TWINS), so what a token may do is
106
+ * what authorize() says its role may: a developer-capped token reads the
107
+ * registers and meets the developer's 403 on the admin and pm writes, and a
108
+ * token its holder minted to act as their role writes them as its holder —
109
+ * directly, with no draft in the approval queue.
110
+ */
111
+ const enc = encodeURIComponent;
112
+ const LEVELS = {
113
+ project: {
114
+ arg: 'project_id',
115
+ help: 'From whoami.',
116
+ base: (a) => `/agent/projects/${enc(a.project_id)}`,
117
+ },
118
+ studio: {
119
+ arg: 'studio_id',
120
+ help: 'The studio, from whoami (a studio membership’s org id).',
121
+ base: (a) => `/agent/studios/${enc(a.studio_id)}`,
122
+ },
123
+ };
124
+
125
+ const ROLE_NOTE =
126
+ ' What your token may do here is what your role may in the browser: a token '
127
+ + 'acting as a developer gets the developer’s 403 on what only an admin or pm '
128
+ + 'writes, and one minted to act as your role writes as you.';
129
+
130
+ /**
131
+ * One family as one tool.
132
+ *
133
+ * @param spec.actions action -> { method, path(args), id?: true, body?: false
134
+ * | (args) => object, run?: (client, args, base) => any,
135
+ * help }. `id: true` means the action names a row by
136
+ * the family's id argument; `body: false` means it sends
137
+ * none (and so refuses `fields`).
138
+ */
139
+ function familyTool({ name, description, level = 'project', id, fields, actions, roleNote = true }) {
140
+ const where = LEVELS[level];
141
+ const properties = {
142
+ [where.arg]: { type: 'string', description: where.help },
143
+ action: {
144
+ type: 'string',
145
+ enum: Object.keys(actions),
146
+ description: Object.entries(actions).map(([a, s]) => `${a} — ${s.help}`).join(' '),
147
+ },
148
+ };
149
+ if (id) properties[id.name] = { type: 'string', description: id.help };
150
+ if (fields) properties.fields = { type: 'object', description: fields };
151
+ return {
152
+ name,
153
+ description: roleNote ? description + ROLE_NOTE : description,
154
+ input: {
155
+ type: 'object',
156
+ properties,
157
+ required: [where.arg, 'action'],
158
+ additionalProperties: false,
159
+ },
160
+ run: async (client, args) => {
161
+ const spec = actions[args.action];
162
+ if (spec.id && !args[id.name]) {
163
+ throw new LoopableError(400, `${name}: ${args.action} needs ${id.name}`);
164
+ }
165
+ // Only an action whose body IS the fields takes them; a read, a fixed
166
+ // body (dismiss) or no body (delete) would drop them on the floor, and
167
+ // a model should be told rather than have its edit quietly vanish.
168
+ const takesFields = spec.method !== 'GET' && spec.body === undefined && !spec.run;
169
+ if (args.fields !== undefined && !takesFields) {
170
+ throw new LoopableError(400, `${name}: ${args.action} takes no fields`);
171
+ }
172
+ const base = where.base(args);
173
+ if (spec.run) return spec.run(client, args, base);
174
+ const init = { method: spec.method };
175
+ if (spec.method !== 'GET' && spec.body !== false) {
176
+ init.body = JSON.stringify(typeof spec.body === 'function' ? spec.body(args) : (args.fields ?? {}));
177
+ }
178
+ return client.call(`${base}${spec.path(args)}`, spec.method === 'GET' ? {} : init);
179
+ },
180
+ };
181
+ }
182
+
183
+ const FAMILY_TOOLS = [
184
+ familyTool({
185
+ name: 'features',
186
+ description:
187
+ 'Create or edit a FEATURE — a surface of the product a person can point '
188
+ + 'at, with a lifecycle (proposed, building, live, retired, superseded). '
189
+ + 'Reading them rides list_backlog. Only people write a feature: this '
190
+ + 'works only on a token its holder minted to act as their role, and any '
191
+ + 'other token is refused with a 403 saying to propose it instead (propose '
192
+ + 'with kind feature) — do that, rather than retrying.',
193
+ id: { name: 'feature_id', help: 'The feature to edit, by id or ref (7), from list_backlog.' },
194
+ fields: 'create: title (required), body, internal (true hides it from the client — a curator’s '
195
+ + 'call). update: any of title, body, status (proposed | building | live | retired | '
196
+ + 'superseded — superseded needs superseded_by, the successor feature), internal, position.',
197
+ actions: {
198
+ create: { method: 'POST', path: () => '/features', help: 'a new feature, from fields.' },
199
+ update: { method: 'PATCH', id: true, path: (a) => `/features/${enc(a.feature_id)}`, help: 'edit feature_id with fields.' },
200
+ },
201
+ }),
202
+
203
+ {
204
+ name: 'record_decision',
205
+ description:
206
+ 'Record what the studio has decided — or change course: pass supersedes_id '
207
+ + 'to write a new decision that supersedes a standing one (decisions are '
208
+ + 'never edited; the old row stays as history). Recording commits the '
209
+ + 'studio, so the scope is admin and pm: a token acting as a developer gets '
210
+ + 'a 403, and a token minted to act as an admin’s or pm’s role records it '
211
+ + 'directly, as them, with nothing in the approval queue. Read '
212
+ + 'list_decisions first — the one you would supersede is there, with its id.',
213
+ input: {
214
+ type: 'object',
215
+ properties: {
216
+ project_id: { type: 'string', description: 'From whoami.' },
217
+ what: { type: 'string', description: 'What was decided, in one or two sentences.' },
218
+ why: { type: 'string', description: 'The reasoning — studio-only; a client never reads it.' },
219
+ kind: { type: 'string', enum: ['decision', 'sign_off', 'change_request'] },
220
+ reversibility: { type: 'string', enum: ['reversible', 'one_way'] },
221
+ alternatives: { type: 'string', description: 'What else was considered.' },
222
+ impact: { type: 'string', description: 'What it changes.' },
223
+ supersedes_id: { type: 'string', description: 'The standing decision this replaces, from list_decisions.' },
224
+ work_item_ids: {
225
+ type: 'array',
226
+ items: { type: 'string' },
227
+ description: 'Work items this decision is about — by id or ref (41).',
228
+ },
229
+ },
230
+ required: ['project_id', 'what'],
231
+ additionalProperties: false,
232
+ },
233
+ run: (client, { project_id, ...decision }) =>
234
+ client.call(`/agent/projects/${enc(project_id)}/decisions`, {
235
+ method: 'POST',
236
+ body: JSON.stringify(decision),
237
+ }),
238
+ },
239
+
240
+ familyTool({
241
+ name: 'raid',
242
+ description:
243
+ 'The RAID register: risks, assumptions, issues and dependencies. Every '
244
+ + 'studio role writes it — noticing a risk is never a privilege — so note '
245
+ + 'one when you find it while working.',
246
+ id: { name: 'entry_id', help: 'The entry to edit, from list.' },
247
+ fields: 'create: category (risk | assumption | issue | dependency, required), title (required), '
248
+ + 'body, severity (low | medium | high), owner_name, review_by (a date like 2026-12-01). '
249
+ + 'update: any of those, status (open | mitigating | closed), reviewed: true with review_note.',
250
+ actions: {
251
+ list: { method: 'GET', path: () => '/raid', help: 'every entry.' },
252
+ create: { method: 'POST', path: () => '/raid', help: 'a new entry, from fields.' },
253
+ update: { method: 'PATCH', id: true, path: (a) => `/raid/${enc(a.entry_id)}`, help: 'edit entry_id with fields.' },
254
+ },
255
+ }),
256
+
257
+ familyTool({
258
+ name: 'stakeholders',
259
+ description:
260
+ 'The stakeholder roster: who matters to this project, on which side, and '
261
+ + 'how often they want to hear. Studio-only, and admin and pm write it.',
262
+ id: { name: 'stakeholder_id', help: 'The stakeholder to edit, from list.' },
263
+ fields: 'create: name (required), role, side (client | studio | third_party), interest, cadence, '
264
+ + 'contact. update: any of those, archived (true or false), user_id (link to a member, or null).',
265
+ actions: {
266
+ list: { method: 'GET', path: () => '/stakeholders', help: 'the roster.' },
267
+ create: { method: 'POST', path: () => '/stakeholders', help: 'a new stakeholder, from fields.' },
268
+ update: { method: 'PATCH', id: true, path: (a) => `/stakeholders/${enc(a.stakeholder_id)}`, help: 'edit stakeholder_id with fields.' },
269
+ },
270
+ }),
271
+
272
+ familyTool({
273
+ name: 'commitments',
274
+ description:
275
+ 'The commitments ledger: what was promised out loud, by whom, and by when '
276
+ + '— the studio to the client, or the client to the studio. Recording one '
277
+ + 'speaks for the studio, so admin and pm write it.',
278
+ id: { name: 'commitment_id', help: 'The commitment to edit, from list.' },
279
+ fields: 'create: what (required), direction (studio_to_client | client_to_studio, required), '
280
+ + 'stakeholder_id, made_by, made_on, due_on (dates like 2026-12-01). update: any of those, '
281
+ + 'status (open | met | withdrawn) with status_note.',
282
+ actions: {
283
+ list: { method: 'GET', path: () => '/commitments', help: 'the ledger.' },
284
+ create: { method: 'POST', path: () => '/commitments', help: 'a new commitment, from fields.' },
285
+ update: { method: 'PATCH', id: true, path: (a) => `/commitments/${enc(a.commitment_id)}`, help: 'edit commitment_id with fields.' },
286
+ },
287
+ }),
288
+
289
+ familyTool({
290
+ name: 'evidence',
291
+ description:
292
+ 'The evidence register: what the world has said — a client remark, usage, '
293
+ + 'support, the market — tagged to the features it is about. Every studio '
294
+ + 'role writes it. A signal is dismissed, never deleted.',
295
+ id: { name: 'signal_id', help: 'The signal to edit, dismiss or restore, from list.' },
296
+ fields: 'create: summary (required), detail, kind (client_said | usage | support | market | other), '
297
+ + 'observed_on (a date), feature_ids (by id or ref). update: any of those.',
298
+ actions: {
299
+ list: { method: 'GET', path: () => '/evidence', help: 'every signal.' },
300
+ create: { method: 'POST', path: () => '/evidence', help: 'a new signal, from fields.' },
301
+ update: { method: 'PATCH', id: true, path: (a) => `/evidence/${enc(a.signal_id)}`, help: 'edit signal_id with fields.' },
302
+ dismiss: {
303
+ method: 'PATCH', id: true, body: () => ({ dismissed: true }),
304
+ path: (a) => `/evidence/${enc(a.signal_id)}`, help: 'set signal_id aside.',
305
+ },
306
+ restore: {
307
+ method: 'PATCH', id: true, body: () => ({ dismissed: false }),
308
+ path: (a) => `/evidence/${enc(a.signal_id)}`, help: 'bring a dismissed signal_id back.',
309
+ },
310
+ },
311
+ }),
312
+
313
+ familyTool({
314
+ name: 'environments',
315
+ description:
316
+ 'Where the project runs: the registered production, staging and preview '
317
+ + 'environments, and the versions recorded on each. Registering one '
318
+ + 'AUTHORIZES Loopable to fetch that address, so admin and pm write it; '
319
+ + 'everyone at the studio reads it.',
320
+ id: { name: 'environment_id', help: 'The environment, from list.' },
321
+ fields: 'create: kind (production | staging | preview, required), base_url (required), version_url. '
322
+ + 'update: any of those. record_version: sha (required).',
323
+ actions: {
324
+ list: { method: 'GET', path: () => '/environments', help: 'the environments, with whether work may be dispatched.' },
325
+ create: { method: 'POST', path: () => '/environments', help: 'register one, from fields.' },
326
+ update: { method: 'PATCH', id: true, path: (a) => `/environments/${enc(a.environment_id)}`, help: 'edit environment_id with fields.' },
327
+ delete: {
328
+ method: 'DELETE', id: true, body: false,
329
+ path: (a) => `/environments/${enc(a.environment_id)}`, help: 'unregister environment_id.',
330
+ },
331
+ record_version: {
332
+ method: 'POST', id: true,
333
+ path: (a) => `/environments/${enc(a.environment_id)}/versions`, help: 'log the sha now running on environment_id.',
334
+ },
335
+ },
336
+ }),
337
+
338
+ familyTool({
339
+ name: 'visibility',
340
+ description:
341
+ 'The switches deciding which registers a client sees: show_signoffs, '
342
+ + 'show_decisions, show_commitments, show_raid, show_evidence, show_pulse. '
343
+ + 'Deciding what a client sees is the curators’ act — admin and pm.',
344
+ fields: 'set: any of the switches, each true or false; the ones left out keep their value.',
345
+ actions: {
346
+ get: { method: 'GET', path: () => '/visibility', help: 'the switches as they stand.' },
347
+ set: { method: 'PUT', path: () => '/visibility', help: 'flip the switches given in fields.' },
348
+ },
349
+ }),
350
+
351
+ familyTool({
352
+ name: 'budgets',
353
+ description:
354
+ 'What the product owner may spend this month, per tier (po, harness, '
355
+ + 'cast), and what it has spent. Reading is every studio role’s — '
356
+ + '"over the budget" is why a product owner goes quiet. Setting a cap is '
357
+ + 'admin and pm.',
358
+ fields: 'set: po, harness, cast — each a monthly cap in USD, or null for none; a tier left out is unchanged.',
359
+ actions: {
360
+ get: { method: 'GET', path: () => '/budgets', help: 'caps and spend.' },
361
+ set: { method: 'PUT', path: () => '/budgets', help: 'set the caps given in fields.' },
362
+ },
363
+ }),
364
+
365
+ familyTool({
366
+ name: 'po_config',
367
+ description:
368
+ 'The product owner’s configuration: the project profile (the world it '
369
+ + 'describes), the persona (how it speaks, versioned) and the foundation '
370
+ + 'documents it is grounded in. The studio’s own — a client never reads '
371
+ + 'it. Admin and pm write it.',
372
+ id: { name: 'doc_id', help: 'The foundation document, from list_foundations.' },
373
+ fields: 'profile: any of description, audience, scope, glossary. persona: any of name, tone, '
374
+ + 'language, instructions. save_foundation: title and body (with doc_id in fields to write '
375
+ + 'the next version of an existing one; without, a new document).',
376
+ actions: {
377
+ get: { method: 'GET', path: () => '/settings', help: 'profile and persona as they stand.' },
378
+ profile: { method: 'PATCH', path: () => '/profile', help: 'overwrite the profile fields given.' },
379
+ persona: { method: 'PATCH', path: () => '/persona', help: 'write the next persona version.' },
380
+ list_foundations: { method: 'GET', path: () => '/foundations', help: 'the foundation documents.' },
381
+ save_foundation: { method: 'PUT', path: () => '/foundations', help: 'a new document, or the next version of one.' },
382
+ archive_foundation: {
383
+ method: 'POST', id: true, body: false,
384
+ path: (a) => `/foundations/${enc(a.doc_id)}/archive`, help: 'retire doc_id.',
385
+ },
386
+ },
387
+ }),
388
+
389
+ familyTool({
390
+ name: 'studio_members',
391
+ level: 'studio',
392
+ roleNote: false,
393
+ description:
394
+ 'Who is in the studio, and their role. These are studio settings, which '
395
+ + 'NO token reaches, whatever role it acts as — a token handing out seats '
396
+ + 'is the thing the ceiling exists to stop — so every action answers a '
397
+ + '403 today. Ask the person to do it in the browser.',
398
+ id: { name: 'user_id', help: 'The member, from list.' },
399
+ fields: 'set_role: role (admin | pm | developer).',
400
+ actions: {
401
+ list: {
402
+ method: 'GET', path: () => '/settings', help: 'the members.',
403
+ run: async (client, _args, base) => {
404
+ const { members } = await client.call(`${base}/settings`);
405
+ return { members };
406
+ },
407
+ },
408
+ set_role: { method: 'PATCH', id: true, path: (a) => `/members/${enc(a.user_id)}`, help: 'change user_id’s role.' },
409
+ remove: {
410
+ method: 'POST', id: true, body: false,
411
+ path: (a) => `/members/${enc(a.user_id)}/remove`, help: 'take user_id out of the studio.',
412
+ },
413
+ },
414
+ }),
415
+
416
+ familyTool({
417
+ name: 'invites',
418
+ level: 'studio',
419
+ roleNote: false,
420
+ description:
421
+ 'Asking somebody into the studio or into a client organization, and '
422
+ + 're-sending an invitation whose temporary password may have run out. '
423
+ + 'Studio settings, which NO token reaches whatever role it acts as, so '
424
+ + 'every action answers a 403 today. Ask the person to do it in the browser.',
425
+ id: { name: 'invite_id', help: 'The pending invitation, from list.' },
426
+ fields: 'invite: email (required), kind (studio | client), role (admin | pm | developer, for a '
427
+ + 'studio seat), org_id (the client organization, for a client seat).',
428
+ actions: {
429
+ list: {
430
+ method: 'GET', path: () => '/settings', help: 'the pending invitations.',
431
+ run: async (client, _args, base) => {
432
+ const { invites } = await client.call(`${base}/settings`);
433
+ return { invites };
434
+ },
435
+ },
436
+ invite: { method: 'POST', path: () => '/invites', help: 'ask somebody, from fields.' },
437
+ cancel: {
438
+ method: 'POST', id: true, body: false,
439
+ path: (a) => `/invites/${enc(a.invite_id)}/cancel`, help: 'un-ask invite_id.',
440
+ },
441
+ /*
442
+ * RE-SEND IS CANCEL AND ASK AGAIN, the browser's own gesture (374): a
443
+ * new invitation for an account that never signed in mails a fresh
444
+ * temporary password (createInvite), and the pending one has to go
445
+ * first or the second is a 409. Read first so the new one is the same
446
+ * seat — email, kind, role, organization — not a guess at it.
447
+ */
448
+ resend: {
449
+ method: 'POST', id: true, help: 'cancel invite_id and send it again, same seat.',
450
+ path: () => '/invites',
451
+ run: async (client, args, base) => {
452
+ const { invites = [] } = await client.call(`${base}/settings`);
453
+ const was = invites.find((i) => i.id === args.invite_id);
454
+ if (!was) throw new LoopableError(404, 'invites: no pending invitation with that id');
455
+ await client.call(`${base}/invites/${enc(was.id)}/cancel`, { method: 'POST' });
456
+ const seat = { email: was.email, kind: was.kind, role: was.role };
457
+ if (was.kind !== 'studio' && was.org_id) seat.org_id = was.org_id;
458
+ return client.call(`${base}/invites`, { method: 'POST', body: JSON.stringify(seat) });
459
+ },
460
+ },
461
+ },
462
+ }),
463
+
464
+ familyTool({
465
+ name: 'approval_queue',
466
+ description:
467
+ 'The approval queue, read: what is waiting for a person to accept, reword '
468
+ + 'or decline — each draft with who proposed it and what approving it '
469
+ + 'changes — and, as history, what left it without becoming anything '
470
+ + '(declined, expired, moot) with the reason. Every studio role reads it; '
471
+ + 'deciding is a person’s, in the browser.',
472
+ actions: {
473
+ pending: { method: 'GET', path: () => '/drafts', help: 'the drafts waiting.' },
474
+ history: { method: 'GET', path: () => '/drafts/history', help: 'what was declined or withdrawn, and why.' },
475
+ },
476
+ }),
477
+ ];
478
+
93
479
  /**
94
480
  * The tools, in the order an agent uses them: find out where you are, read
95
481
  * what you are meant to build, write down work, propose work that is not
@@ -492,8 +878,8 @@ export const TOOLS = [
492
878
  required: ['project_id'],
493
879
  additionalProperties: false,
494
880
  },
495
- // Read-only, and the write could not be added here: recording a decision
496
- // is a person committing the studio, and the /agent surface has no POST.
881
+ // The write is record_decision, below: a person's act the scope keeps to
882
+ // admin and pm, which only a full-role token of theirs passes (395).
497
883
  run: (client, { project_id }) =>
498
884
  client.call(`/agent/projects/${encodeURIComponent(project_id)}/decisions`),
499
885
  },
@@ -733,43 +1119,25 @@ export const TOOLS = [
733
1119
  {
734
1120
  name: 'report_progress',
735
1121
  /*
736
- * THE ENUM IS THE AGENT'S HALF OF THE TRANSITION TABLE, plus the three
737
- * edges a person may hand their own token (342). `ready`, `verifying` and
738
- * `done` are a person's words — grooming, deploying and accepting are
739
- * seats a person sits in — and the API refuses them from a token whose
740
- * holder did not mint it with the grant, whatever this file offers. They
741
- * are offered because a token minted with it may take them, for its
742
- * holder, when the holder asks; the description says so, and says that
743
- * without the grant the answer is a 403 — except todo → ready on an item
744
- * this token filed itself, once readiness has no blockers (364), and
745
- * in_review → verifying at the merge (365).
746
- * `dropped` is never offered: no token takes it.
1122
+ * EVERY STATUS IS OFFERED (410). A studio token takes any edge a studio
1123
+ * person takes, `done` and `dropped` included, and the trail names the
1124
+ * person and the token for each move. The one condition that remains is
1125
+ * a token's `ready` meeting readiness (380).
747
1126
  */
748
1127
  description:
749
- 'Move a work item to todo, in_progress, in_review, blocked or ' +
750
- 'awaiting_input. This is how the backlog stays true — report it as part ' +
751
- 'of doing the work, not as a chore afterwards, and say WHAT happened in ' +
752
- 'the note ("opened PR 475, tests green"): that sentence exists only ' +
753
- 'right now, and the studio feed is a delivery log exactly as far as ' +
754
- 'people write it. in_review is as far as you go: a person reads the ' +
755
- 'diff, merges, and accepts the work as done. Say blocked when something ' +
756
- 'outside the item is stopping you and awaiting_input when you need an ' +
757
- 'answer — both beat leaving the item claiming work is happening. ' +
758
- 'ready, verifying and done are the person’s, not yours: the API ' +
759
- 'refuses them unless the person who owns your token minted it with the ' +
760
- 'grant to set them, and even then you set one ONLY when that person asks ' +
761
- 'for it in the session and names the items — never on your own judgement ' +
762
- 'that the work is ready or finished. Such a move is recorded as theirs, ' +
763
- 'made through your token. The one exception without the grant: you may ' +
764
- 'set ready only on an item you filed yourself, through this same token, ' +
765
- 'from todo, once its readiness has no blockers (get_item shows ' +
766
- 'ready_blockers) — anything a person or another token filed gets the ' +
767
- '403. And verifying, at the merge: once the pull request of an item in ' +
768
- 'in_review has merged, you may move it in_review → verifying while the ' +
769
- 'deploy owes the checks its close left after_merge. It comes back to ' +
770
- 'in_review only through close_session, with every criterion met — never ' +
771
- 'through this tool. To change what an item SAYS rather than ' +
772
- 'where it is, use revise.',
1128
+ 'Move a work item to any status: todo, ready, in_progress, in_review, ' +
1129
+ 'verifying, done, blocked, awaiting_input or dropped. This is how the ' +
1130
+ 'backlog stays true — report it as part of doing the work, not as a ' +
1131
+ 'chore afterwards, and say WHAT happened in the note ("opened PR 475, ' +
1132
+ 'tests green"): that sentence exists only right now, and the studio ' +
1133
+ 'feed is a delivery log exactly as far as people write it. You move an ' +
1134
+ 'item on your own judgement; the trail records the move under your ' +
1135
+ 'person and this token, and that record is the control. Say blocked ' +
1136
+ 'when something outside the item is stopping you and awaiting_input ' +
1137
+ 'when you need an answer — both beat leaving the item claiming work is ' +
1138
+ 'happening. ready is refused while get_item shows ready_blockers: write ' +
1139
+ 'what is missing first. To change what an item SAYS rather than where ' +
1140
+ 'it is, use revise.',
773
1141
  input: {
774
1142
  type: 'object',
775
1143
  properties: {
@@ -789,6 +1157,7 @@ export const TOOLS = [
789
1157
  'ready',
790
1158
  'verifying',
791
1159
  'done',
1160
+ 'dropped',
792
1161
  ],
793
1162
  },
794
1163
  note: {
@@ -1163,6 +1532,9 @@ export const TOOLS = [
1163
1532
  { method: 'POST', body: JSON.stringify(ending) },
1164
1533
  ),
1165
1534
  },
1535
+
1536
+ // What the UI writes, a tool per family — see FAMILY_TOOLS above.
1537
+ ...FAMILY_TOOLS,
1166
1538
  ];
1167
1539
 
1168
1540
  export const toolByName = (name) => {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@loopable/mcp",
3
- "version": "0.3.11",
3
+ "version": "0.4.1",
4
4
  "description": "The Loopable MCP server: an agent reads the backlog it is meant to build, proposes work, asks the studio a question, and says when it is done.",
5
5
  "license": "MIT",
6
6
  "homepage": "https://loopable.ai",