@loopable/mcp 0.1.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 ADDED
@@ -0,0 +1,102 @@
1
+ # Loopable MCP
2
+
3
+ An MCP server so an agent can read the backlog it is meant to build, propose
4
+ work, and say when it has done it — without a browser, and without a second
5
+ authorization path.
6
+
7
+ Published as `@loopable/mcp`. The [loopable plugin](../plugin/) registers it
8
+ for Claude Code; any other MCP host runs it the same way:
9
+
10
+ ```json
11
+ { "mcpServers": { "loopable": { "command": "npx", "args": ["-y", "@loopable/mcp@latest"] } } }
12
+ ```
13
+
14
+ ## Getting a token in
15
+
16
+ ```bash
17
+ mkdir -p ~/.config/loopable
18
+ printf '%s' 'lpb_…' > ~/.config/loopable/token
19
+ chmod 600 ~/.config/loopable/token
20
+ ```
21
+
22
+ `.mcp.json` at the repo root registers this server and names **no secret**, so
23
+ there is nothing in a tracked file to leak and nothing to redact before
24
+ pushing. The token lives in a file only you can read; the server picks it up on
25
+ the next tool call, so dropping it in place does not need a restart.
26
+
27
+ `LOOPABLE_TOKEN` (the value) and `LOOPABLE_TOKEN_FILE` (another path) still win
28
+ over the default if set — that is how CI would inject one. An empty or
29
+ unexpanded `${LOOPABLE_TOKEN}` is ignored rather than sent, which is worth a
30
+ line of code because the alternative is a 401 that blames your credential for
31
+ your configuration. See `lib/token.mjs`.
32
+
33
+ Without a token anywhere the server still starts and lists its tools; calling
34
+ one says how to get one. That is deliberate — everybody working in this repo
35
+ gets this server, and most of them do not have a token.
36
+
37
+ ## What it can do
38
+
39
+ | tool | |
40
+ |---|---|
41
+ | `whoami` | which account the token acts as, and what it can see |
42
+ | `list_backlog` | one project's work items |
43
+ | `add_item` | write work into the backlog, under a parent if it has one |
44
+ | `propose` | put somebody else's ask in the approval queue — **not** in the backlog |
45
+ | `revise` | correct an item's title or body |
46
+ | `report_progress` | move an item to todo / in_progress / done |
47
+
48
+ ## The two things to know
49
+
50
+ **An agent is a member.** The token resolves to an ordinary `users` row holding
51
+ ordinary memberships (`api/lib/agent-tokens.mjs`), so everything in
52
+ `api/lib/authz.mjs` applies to it unchanged. This server has no privileged
53
+ path and could not create one: it calls the same routes a browser does, and
54
+ those routes are generated from one list so an agent can never reach something
55
+ a person with the same membership cannot. Narrowing what an agent may touch
56
+ means giving it a membership with a smaller role.
57
+
58
+ **The backlog and the queue are for different things.** `add_item` writes
59
+ straight into the backlog; `propose` puts a draft in the approval queue for a
60
+ human to accept, reword or decline. The line between them is not how much we
61
+ trust the caller — it is where the work came from.
62
+
63
+ The backlog is the **studio's own**. `lib/scopes.mjs` has granted
64
+ `backlog: write` to every studio role since the policy was first written, so a
65
+ member writing in it is a member doing their job, and an agent holding a
66
+ developer's membership is doing the same job. The approval queue is for what
67
+ arrives from **outside** that: a client asking, or the product owner drafting a
68
+ requirement out of a conversation. Those need a human to accept them because
69
+ somebody outside the studio is owed an answer either way.
70
+
71
+ Putting our own decided work through the queue as well would not add a
72
+ safeguard. It would add a rubber stamp — and a queue that is stamped fifty times
73
+ in a row stops being read, which costs exactly the guarantee it was meant to
74
+ give. What is actually guaranteed is narrower and worth keeping: **nothing a
75
+ client asks for, and nothing the product owner drafts, becomes committed work
76
+ without a person agreeing to it.**
77
+
78
+ An earlier version of this file claimed that nothing an agent does reaches the
79
+ backlog without human agreement. That was never what `scopes.mjs` said, and it
80
+ is recorded here rather than quietly deleted because the overclaim is the sort
81
+ of thing that gets believed and then designed around.
82
+
83
+ **What `revise` will not touch.** `client_visible`, `kind` and `parent_id`.
84
+ Visibility is the line between the studio's backlog and what a client reads as
85
+ a roadmap, and `lib/scopes.mjs` describes a developer as somebody who works the
86
+ backlog and has no say in what a client sees — the browser's own edit dialog
87
+ leaves it out for the same reason. Kind and parent are absent because moving an
88
+ item is a different operation with different rules, and `updateItem`'s
89
+ whitelist refuses them anyway.
90
+
91
+ ## Layout
92
+
93
+ ```
94
+ lib/tools.mjs the tools, as plain functions over the HTTP API. No SDK, so
95
+ every decision in here is unit-tested with a stubbed fetch.
96
+ lib/token.mjs where the token comes from, and what is not a token.
97
+ server.mjs the wiring: turns those into a protocol and does nothing else.
98
+ ```
99
+
100
+ That split is the same one `api/lib/router.mjs` makes against the AWS SDK, for
101
+ the same reason: the part that is hard to test should be the part with nothing
102
+ to get wrong.
package/lib/token.mjs ADDED
@@ -0,0 +1,74 @@
1
+ /**
2
+ * Where the token comes from.
3
+ *
4
+ * The first attempt at this put the token in .mcp.json, which is committed —
5
+ * so the secret would have been one `git add -A` from being pushed. The second
6
+ * put it in ~/.claude.json instead, which is safe but does not work: a project
7
+ * .mcp.json shadows the user-scope entry, so the committed
8
+ * `"LOOPABLE_TOKEN": "${LOOPABLE_TOKEN}"` won, expanded to empty, and every
9
+ * call came back 401 with nothing on the wire to say why.
10
+ *
11
+ * So the file that is committed names no secret and no home directory, and the
12
+ * secret lives in a file only its owner can read. Nothing to redact, nothing
13
+ * to leak, and it works the same for the next person who clones this.
14
+ *
15
+ * In order:
16
+ * LOOPABLE_TOKEN the value itself — for CI, where a secret is injected
17
+ * LOOPABLE_TOKEN_FILE a path, if you keep yours somewhere else
18
+ * ~/.config/loopable/token
19
+ */
20
+ import { readFileSync } from 'node:fs';
21
+ import { homedir } from 'node:os';
22
+ import { join } from 'node:path';
23
+
24
+ export const DEFAULT_TOKEN_FILE = join('.config', 'loopable', 'token');
25
+
26
+ /**
27
+ * `${LOOPABLE_TOKEN}` arriving verbatim, unexpanded.
28
+ *
29
+ * Claude Code expands an unset variable in .mcp.json to empty, but not every
30
+ * runner does — some pass the literal through. Treating that as a token sends
31
+ * a dollar sign to the API and gets a 401 that blames the credential instead
32
+ * of the configuration, which is exactly the hour this file exists to save.
33
+ */
34
+ const unexpanded = (value) => /^\$[{(]/.test(value);
35
+
36
+ const clean = (value) => {
37
+ const token = (value ?? '').trim();
38
+ return token && !unexpanded(token) ? token : null;
39
+ };
40
+
41
+ export const NO_TOKEN = [
42
+ 'No Loopable token.',
43
+ `Put one in ~/${DEFAULT_TOKEN_FILE} (chmod 600), or set LOOPABLE_TOKEN_FILE`,
44
+ 'to where you keep it. A studio admin mints one with',
45
+ 'POST /v1/studios/<studio-id>/agent-tokens.',
46
+ ].join(' ');
47
+
48
+ /**
49
+ * @param env process.env, or a stand-in
50
+ * @param read reads a path to a string, or throws — node:fs by default
51
+ * @param home the home directory the default path hangs off
52
+ */
53
+ export function resolveToken({ env = process.env, read = readFileSync, home = homedir() } = {}) {
54
+ const direct = clean(env.LOOPABLE_TOKEN);
55
+ if (direct) return direct;
56
+
57
+ // An explicit path that does not work is an error, never a reason to quietly
58
+ // read a different file: being handed the wrong identity is worse than being
59
+ // handed none, and far harder to notice.
60
+ const named = clean(env.LOOPABLE_TOKEN_FILE);
61
+ const path = named ?? join(home, DEFAULT_TOKEN_FILE);
62
+
63
+ let contents;
64
+ try {
65
+ contents = read(path, 'utf8');
66
+ } catch (err) {
67
+ if (named) throw new Error(`LOOPABLE_TOKEN_FILE is ${path}, which could not be read: ${err.code ?? err.message}`);
68
+ throw new Error(NO_TOKEN);
69
+ }
70
+
71
+ const token = clean(contents);
72
+ if (!token) throw new Error(named ? `${path} is empty` : NO_TOKEN);
73
+ return token;
74
+ }
package/lib/tools.mjs ADDED
@@ -0,0 +1,456 @@
1
+ /**
2
+ * What an agent can do in Loopable, as plain functions over the HTTP API.
3
+ *
4
+ * No MCP SDK in this file, on purpose — the same reason lib/router.mjs holds
5
+ * no AWS SDK. Everything with a decision in it is testable with a stubbed
6
+ * fetch, and server.mjs is the thin wiring that hands these to the protocol.
7
+ *
8
+ * THERE IS NO PRIVILEGED PATH HERE. Every call goes through the ordinary API
9
+ * carrying an ordinary token, which resolves to an ordinary membership. An
10
+ * agent cannot see or do anything a person holding the same membership could
11
+ * not — this file could not widen that if it tried, which is the point of
12
+ * building it this way round.
13
+ */
14
+
15
+ export class LoopableError extends Error {
16
+ constructor(status, message) {
17
+ super(message);
18
+ this.name = 'LoopableError';
19
+ this.status = status;
20
+ }
21
+ }
22
+
23
+ /**
24
+ * @param {object} config { apiUrl, token, fetch? }
25
+ */
26
+ export function makeClient({ apiUrl, token, fetch: doFetch = fetch }) {
27
+ if (!apiUrl) throw new Error('LOOPABLE_API_URL is not set');
28
+ if (!token) throw new Error('LOOPABLE_TOKEN is not set');
29
+
30
+ async function call(path, init = {}) {
31
+ const res = await doFetch(`${apiUrl}${path}`, {
32
+ ...init,
33
+ headers: {
34
+ 'content-type': 'application/json',
35
+ authorization: `Bearer ${token}`,
36
+ ...init.headers,
37
+ },
38
+ });
39
+ if (!res.ok) {
40
+ let message = `HTTP ${res.status}`;
41
+ try {
42
+ const body = await res.json();
43
+ if (body?.error) message = body.error;
44
+ } catch {
45
+ /* not JSON; the status is all there is */
46
+ }
47
+ throw new LoopableError(res.status, message);
48
+ }
49
+ return res.status === 204 ? undefined : res.json();
50
+ }
51
+
52
+ return { call };
53
+ }
54
+
55
+ /**
56
+ * The tools, in the order an agent uses them: find out where you are, read
57
+ * what you are meant to build, write down work, propose work that is not
58
+ * yours to decide, correct what you got wrong, say you have done it.
59
+ *
60
+ * `add_item` and `propose` are the pair worth understanding before choosing
61
+ * between them. They are not two ways to do one thing: the backlog is the
62
+ * STUDIO'S OWN — a member writing in it is a member doing their job, which is
63
+ * why lib/scopes.mjs has granted `backlog: write` to every studio role since
64
+ * the policy was first written. The approval queue is for what arrives from
65
+ * OUTSIDE that: a client asking, or the product owner drafting from a
66
+ * conversation. Routing our own decided work through it would not add a
67
+ * safeguard, it would add a rubber stamp — and a queue everybody stamps is a
68
+ * queue nobody reads.
69
+ *
70
+ * Each `run` returns plain data. Turning that into protocol content is
71
+ * server.mjs's job, so these stay testable and so a different transport could
72
+ * reuse them unchanged.
73
+ */
74
+ export const TOOLS = [
75
+ {
76
+ name: 'whoami',
77
+ description:
78
+ 'Which account this token acts as, which studios and clients it belongs to, ' +
79
+ 'and which projects it can see. Start here when unsure what is reachable.',
80
+ input: { type: 'object', properties: {}, additionalProperties: false },
81
+ run: (client) => client.call('/agent/whoami'),
82
+ },
83
+
84
+ {
85
+ name: 'list_backlog',
86
+ description:
87
+ 'The work items of one project: epic, story, task and bug, with status and ' +
88
+ 'whether the client sees each one. Flat rows; parent_id gives the tree, the ' +
89
+ 'blocking links come back beside the items, and so do the FEATURES — the ' +
90
+ 'surfaces of the product, each with a lifecycle (proposed, building, live, ' +
91
+ 'retired, superseded) — plus the tags saying which work touches which ' +
92
+ 'surface. On any backlog past a few dozen items, START NARROW — titles_only ' +
93
+ 'to orient, status or parent_id to focus, then get_item for the bodies you ' +
94
+ 'actually need. The unfiltered dump of a healthy backlog is bigger than ' +
95
+ 'most contexts want.',
96
+ input: {
97
+ type: 'object',
98
+ properties: {
99
+ project_id: { type: 'string', description: 'From whoami.' },
100
+ status: {
101
+ type: 'string',
102
+ description:
103
+ 'Keep only these statuses, comma-separated — "todo,in_progress" is ' +
104
+ 'what a working session usually wants.',
105
+ },
106
+ parent_id: {
107
+ type: 'string',
108
+ description:
109
+ 'Keep one subtree: this item and everything beneath it. An id that ' +
110
+ 'is not yours to see returns an empty list, not an error.',
111
+ },
112
+ titles_only: {
113
+ type: 'boolean',
114
+ description: 'Drop the bodies. Every other column survives.',
115
+ },
116
+ },
117
+ required: ['project_id'],
118
+ additionalProperties: false,
119
+ },
120
+ run: (client, { project_id, status, parent_id, titles_only }) => {
121
+ const q = new URLSearchParams();
122
+ if (status) q.set('status', status);
123
+ if (parent_id) q.set('parent_id', parent_id);
124
+ if (titles_only) q.set('bodies', 'false');
125
+ const qs = q.toString();
126
+ return client.call(
127
+ `/agent/projects/${encodeURIComponent(project_id)}/items${qs ? `?${qs}` : ''}`,
128
+ );
129
+ },
130
+ },
131
+
132
+ {
133
+ name: 'get_item',
134
+ description:
135
+ 'One work item in full: its body, its children by title, and the ' +
136
+ 'dependency links touching it. The read to make after list_backlog with ' +
137
+ 'titles_only told you which items matter.',
138
+ input: {
139
+ type: 'object',
140
+ properties: {
141
+ project_id: { type: 'string', description: 'From whoami.' },
142
+ item_id: { type: 'string' },
143
+ },
144
+ required: ['project_id', 'item_id'],
145
+ additionalProperties: false,
146
+ },
147
+ run: (client, { project_id, item_id }) =>
148
+ client.call(
149
+ `/agent/projects/${encodeURIComponent(project_id)}/items/${encodeURIComponent(item_id)}`,
150
+ ),
151
+ },
152
+
153
+ {
154
+ name: 'list_decisions',
155
+ description:
156
+ 'What the studio has committed to, newest first: each decision with its ' +
157
+ 'reason, the work items it changed, and whether it still stands (`current`) ' +
158
+ '— changing course writes a new decision naming the one it supersedes, so ' +
159
+ 'a superseded row is history, not policy. Read these BEFORE proposing or ' +
160
+ 'building something they may already have ruled out.',
161
+ input: {
162
+ type: 'object',
163
+ properties: { project_id: { type: 'string', description: 'From whoami.' } },
164
+ required: ['project_id'],
165
+ additionalProperties: false,
166
+ },
167
+ // Read-only, and the write could not be added here: recording a decision
168
+ // is a person committing the studio, and the /agent surface has no POST.
169
+ run: (client, { project_id }) =>
170
+ client.call(`/agent/projects/${encodeURIComponent(project_id)}/decisions`),
171
+ },
172
+
173
+ {
174
+ name: 'ask_studio',
175
+ description:
176
+ 'Hand a question to the studio because it is not yours to decide: two ' +
177
+ 'decisions that seem to conflict, a story that contradicts its epic, ' +
178
+ 'scope you cannot settle from the backlog. It lands in the same inbox ' +
179
+ 'the product owner escalates into, and a person answers or dismisses it. ' +
180
+ 'Ask when genuinely blocked — the answer comes back on the escalation ' +
181
+ 'row, so check list_escalations with status "resolved" later. Who asked ' +
182
+ 'is recorded from your token; you cannot sign anybody else.',
183
+ input: {
184
+ type: 'object',
185
+ properties: {
186
+ project_id: { type: 'string', description: 'From whoami.' },
187
+ reason: {
188
+ type: 'string',
189
+ enum: ['scope', 'schedule', 'price', 'unknown'],
190
+ description: 'What kind of question it is. The inbox groups by this.',
191
+ },
192
+ question: {
193
+ type: 'string',
194
+ description: 'What you need decided, with enough context to decide it.',
195
+ },
196
+ },
197
+ required: ['project_id', 'question'],
198
+ additionalProperties: false,
199
+ },
200
+ run: (client, { project_id, ...ask }) =>
201
+ client.call(`/agent/projects/${encodeURIComponent(project_id)}/questions`, {
202
+ method: 'POST',
203
+ body: JSON.stringify(ask),
204
+ }),
205
+ },
206
+
207
+ {
208
+ name: 'list_escalations',
209
+ description:
210
+ 'The questions waiting on the studio, oldest first — the same inbox a ' +
211
+ 'developer reads in the browser. Default is the open ones; pass status ' +
212
+ '"resolved" to read answers (a question asked with ask_studio carries ' +
213
+ 'its answer on the row), or "open,resolved,dismissed" for everything.',
214
+ input: {
215
+ type: 'object',
216
+ properties: {
217
+ project_id: { type: 'string', description: 'From whoami.' },
218
+ status: {
219
+ type: 'string',
220
+ description: 'Comma-separated: open, resolved, dismissed. Default open.',
221
+ },
222
+ },
223
+ required: ['project_id'],
224
+ additionalProperties: false,
225
+ },
226
+ run: (client, { project_id, status }) =>
227
+ client.call(
228
+ `/agent/projects/${encodeURIComponent(project_id)}/escalations${
229
+ status ? `?status=${encodeURIComponent(status)}` : ''
230
+ }`,
231
+ ),
232
+ },
233
+
234
+ {
235
+ name: 'add_item',
236
+ description:
237
+ 'Write a work item into the backlog: work the studio has decided to do. ' +
238
+ 'Pass parent_id to file it under an epic or story — the parent need only ' +
239
+ 'OUTRANK the item (epic > story > task, levels may be skipped, so a task ' +
240
+ 'sits directly under an epic). A bug stands alone: no parent, no children ' +
241
+ '— it is something broken on a surface, and feature_ids says which. ' +
242
+ 'Features themselves are not work items: to ask for a new surface, use ' +
243
+ 'propose with kind feature. For something SOMEBODY ELSE asked for, use ' +
244
+ 'propose instead.',
245
+ input: {
246
+ type: 'object',
247
+ properties: {
248
+ project_id: { type: 'string', description: 'From whoami.' },
249
+ title: { type: 'string' },
250
+ body: { type: 'string' },
251
+ kind: { type: 'string', enum: ['epic', 'story', 'task', 'bug'] },
252
+ parent_id: {
253
+ type: 'string',
254
+ description: 'An existing item of a broader kind than this one — epic > story > task, and levels may be skipped. Omit for a root; a bug never has one.',
255
+ },
256
+ feature_ids: {
257
+ type: 'array',
258
+ items: { type: 'string' },
259
+ description: 'The features (surfaces) this work touches — ids from list_backlog. One is usual, several is legal, none is fine.',
260
+ },
261
+ },
262
+ required: ['project_id', 'title'],
263
+ additionalProperties: false,
264
+ },
265
+ // parent_kind is NOT sent and could not be: the API reads it from the
266
+ // parent row so that a caller cannot claim a parent is something it is
267
+ // not. Sending our own would at best be ignored and at worst be believed.
268
+ run: (client, { project_id, ...item }) =>
269
+ client.call(`/agent/projects/${encodeURIComponent(project_id)}/items`, {
270
+ method: 'POST',
271
+ body: JSON.stringify(item),
272
+ }),
273
+ },
274
+
275
+ {
276
+ name: 'propose',
277
+ description:
278
+ 'Propose a work item somebody else asked for — or a NEW FEATURE (kind ' +
279
+ 'feature proposes a surface of the product; approving one creates it on ' +
280
+ 'the feature plane, not in the backlog). It goes to the approval queue ' +
281
+ 'for a human to accept, reword or decline — it does NOT become work. Say ' +
282
+ 'what was asked and who asked. For work the studio has already decided to ' +
283
+ 'do, use add_item instead.',
284
+ input: {
285
+ type: 'object',
286
+ properties: {
287
+ project_id: { type: 'string' },
288
+ title: { type: 'string' },
289
+ body: { type: 'string' },
290
+ kind: { type: 'string', enum: ['feature', 'epic', 'story', 'task', 'bug'] },
291
+ asked_by: { type: 'string' },
292
+ asked: { type: 'string' },
293
+ },
294
+ required: ['project_id', 'title'],
295
+ additionalProperties: false,
296
+ },
297
+ run: (client, { project_id, ...draft }) =>
298
+ client.call(`/agent/projects/${encodeURIComponent(project_id)}/drafts`, {
299
+ method: 'POST',
300
+ body: JSON.stringify(draft),
301
+ }),
302
+ },
303
+
304
+ {
305
+ name: 'revise',
306
+ description:
307
+ 'Correct the words of an existing work item — its title, its body, or both. ' +
308
+ 'For work that has moved along rather than been reworded, use report_progress.',
309
+ input: {
310
+ type: 'object',
311
+ properties: {
312
+ project_id: { type: 'string' },
313
+ item_id: { type: 'string' },
314
+ title: { type: 'string' },
315
+ body: { type: 'string' },
316
+ },
317
+ required: ['project_id', 'item_id'],
318
+ additionalProperties: false,
319
+ },
320
+ /*
321
+ * WHAT IS NOT HERE: client_visible, kind and parent_id.
322
+ *
323
+ * Visibility is the line between the studio's working backlog and what a
324
+ * client reads as a roadmap. lib/scopes.mjs describes a developer as
325
+ * someone who "works the backlog; no say in what a client sees", and the
326
+ * browser's own edit dialog leaves it out for the same reason. An agent
327
+ * quietly moving something onto a client's roadmap is precisely the act
328
+ * that should cost a person a click.
329
+ *
330
+ * Kind and parent used to be absent because the API refused them anyway.
331
+ * It still refuses them HERE — updateItem's whitelist has never included
332
+ * them — but there is a move route now, so their absence has stopped being
333
+ * a consequence and become a choice, and a comment that keeps giving the
334
+ * old reason is how a deliberate decision gets reversed by accident.
335
+ *
336
+ * The choice: adding to a backlog is an agent's job and restructuring one
337
+ * is a bigger act — and it is about to become a PUBLISHING act, because
338
+ * once a client's view is inherited from an item's ancestors, moving a
339
+ * story out from under an internal parent shows it to somebody outside the
340
+ * studio with no toggle anywhere in the request. Opening this up belongs
341
+ * after the guard for that exists, not before.
342
+ */
343
+ run: (client, { project_id, item_id, ...edits }) => {
344
+ // Caught here rather than in the 400 it would earn, because "revise: say
345
+ // what to change" names the tool and the mistake, and `nothing to change`
346
+ // names neither.
347
+ if (edits.title === undefined && edits.body === undefined) {
348
+ throw new LoopableError(400, 'revise: give a title, a body, or both');
349
+ }
350
+ return client.call(
351
+ `/agent/projects/${encodeURIComponent(project_id)}/items/${encodeURIComponent(item_id)}`,
352
+ { method: 'PATCH', body: JSON.stringify(edits) },
353
+ );
354
+ },
355
+ },
356
+
357
+ {
358
+ name: 'link_items',
359
+ description:
360
+ 'Record that one item has to be done before another can be: blocker_id ' +
361
+ 'first, blocked_id second. One edge, read from both ends — there is no ' +
362
+ 'separate "blocked by". Say it when you find it, which is usually while ' +
363
+ 'working rather than while planning. A ring is refused.',
364
+ input: {
365
+ type: 'object',
366
+ properties: {
367
+ project_id: { type: 'string', description: 'From whoami.' },
368
+ blocker_id: { type: 'string', description: 'Has to be done first.' },
369
+ blocked_id: { type: 'string', description: 'Cannot start until the blocker is done.' },
370
+ },
371
+ required: ['project_id', 'blocker_id', 'blocked_id'],
372
+ additionalProperties: false,
373
+ },
374
+ /*
375
+ * SHARED, unlike moving an item. Noticing that one thing cannot start until
376
+ * another lands is the same KIND of fact as reporting progress, and it is
377
+ * most often noticed by whatever is doing the work. It also cannot publish
378
+ * anything: a link says nothing about who may read either end.
379
+ *
380
+ * There is no unlink here, deliberately. An agent noticing a dependency is
381
+ * it doing its job; an agent quietly removing one a person stated is not.
382
+ */
383
+ run: (client, { project_id, blocker_id, blocked_id }) =>
384
+ client.call(`/agent/projects/${encodeURIComponent(project_id)}/links`, {
385
+ method: 'POST',
386
+ body: JSON.stringify({ blocker_id, blocked_id }),
387
+ }),
388
+ },
389
+ {
390
+ name: 'report_progress',
391
+ description:
392
+ 'Move a work item to todo, in_progress or done. This is how the backlog ' +
393
+ 'stays true — report it as part of finishing, not as a chore afterwards, ' +
394
+ 'and say WHAT happened in the note ("shipped in PR 475, verified live"): ' +
395
+ 'that sentence exists only right now, and the studio feed is a delivery ' +
396
+ 'log exactly as far as people write it. To change what an item SAYS ' +
397
+ 'rather than where it is, use revise.',
398
+ input: {
399
+ type: 'object',
400
+ properties: {
401
+ project_id: { type: 'string' },
402
+ item_id: { type: 'string' },
403
+ status: { type: 'string', enum: ['todo', 'in_progress', 'done'] },
404
+ note: {
405
+ type: 'string',
406
+ description:
407
+ 'One sentence about this move, for the studio. Replaced by the ' +
408
+ 'next status change; clients never see it raw.',
409
+ },
410
+ },
411
+ required: ['project_id', 'item_id', 'status'],
412
+ additionalProperties: false,
413
+ },
414
+ run: (client, { project_id, item_id, status, note }) =>
415
+ client.call(
416
+ `/agent/projects/${encodeURIComponent(project_id)}/items/${encodeURIComponent(item_id)}`,
417
+ // Sent only when given. The API settles the note on EVERY status
418
+ // write — provided or empty — so omitting it here still clears a
419
+ // stale one; what this avoids is serializing `note: undefined`.
420
+ { method: 'PATCH', body: JSON.stringify(note ? { status, note } : { status }) },
421
+ ),
422
+ },
423
+ ];
424
+
425
+ export const toolByName = (name) => {
426
+ const tool = TOOLS.find((t) => t.name === name);
427
+ if (!tool) throw new LoopableError(400, `unknown tool: ${name}`);
428
+ return tool;
429
+ };
430
+
431
+ /**
432
+ * Run one, with its arguments checked against its own schema first.
433
+ *
434
+ * Required fields and unknown fields are both refused here rather than being
435
+ * sent — a model that invents an argument should be told so, not have it
436
+ * silently dropped into a request that then fails for a different reason.
437
+ */
438
+ export async function runTool(client, name, args = {}) {
439
+ const tool = toolByName(name);
440
+ const { properties, required = [] } = tool.input;
441
+
442
+ for (const key of required) {
443
+ if (args[key] === undefined || args[key] === '') {
444
+ throw new LoopableError(400, `${name}: ${key} is required`);
445
+ }
446
+ }
447
+ for (const key of Object.keys(args)) {
448
+ if (!(key in properties)) throw new LoopableError(400, `${name}: unknown argument ${key}`);
449
+ const spec = properties[key];
450
+ if (spec.enum && args[key] !== undefined && !spec.enum.includes(args[key])) {
451
+ throw new LoopableError(400, `${name}: ${key} must be one of ${spec.enum.join(', ')}`);
452
+ }
453
+ }
454
+
455
+ return tool.run(client, args);
456
+ }
package/package.json ADDED
@@ -0,0 +1,40 @@
1
+ {
2
+ "name": "@loopable/mcp",
3
+ "version": "0.1.0",
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
+ "license": "MIT",
6
+ "homepage": "https://loopable.ai",
7
+ "repository": {
8
+ "type": "git",
9
+ "url": "https://github.com/loopable-ai/claude-plugins"
10
+ },
11
+ "keywords": [
12
+ "loopable",
13
+ "mcp",
14
+ "model-context-protocol",
15
+ "backlog",
16
+ "product-owner"
17
+ ],
18
+ "type": "module",
19
+ "bin": {
20
+ "loopable-mcp": "./server.mjs"
21
+ },
22
+ "files": [
23
+ "server.mjs",
24
+ "lib/",
25
+ "README.md"
26
+ ],
27
+ "engines": {
28
+ "node": ">=20"
29
+ },
30
+ "publishConfig": {
31
+ "access": "public"
32
+ },
33
+ "scripts": {
34
+ "start": "node server.mjs",
35
+ "test": "node --test \"test/*.test.mjs\""
36
+ },
37
+ "dependencies": {
38
+ "@modelcontextprotocol/sdk": "^1.0.0"
39
+ }
40
+ }
package/server.mjs ADDED
@@ -0,0 +1,74 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * Loopable, as an MCP server.
4
+ *
5
+ * Thin on purpose: everything with a decision in it is in lib/tools.mjs, which
6
+ * imports no SDK and is unit-tested. This file turns those functions into a
7
+ * protocol and does nothing else, so the part that cannot easily be tested is
8
+ * the part with nothing to get wrong.
9
+ *
10
+ * node server.mjs # token from ~/.config/loopable/token — see lib/token.mjs
11
+ *
12
+ * The token is an ordinary member's credential (see api/lib/agent-tokens.mjs).
13
+ * Everything this server can do, the person holding that membership can do —
14
+ * there is no privileged path, and this file could not create one.
15
+ */
16
+ import { Server } from '@modelcontextprotocol/sdk/server/index.js';
17
+ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
18
+ import {
19
+ CallToolRequestSchema,
20
+ ListToolsRequestSchema,
21
+ } from '@modelcontextprotocol/sdk/types.js';
22
+ import { LoopableError, TOOLS, makeClient, runTool } from './lib/tools.mjs';
23
+ import { resolveToken } from './lib/token.mjs';
24
+
25
+ /**
26
+ * Built on first use, not at startup.
27
+ *
28
+ * The server is registered in this repo's .mcp.json, so every session in it
29
+ * starts one — including sessions belonging to somebody who has no token and
30
+ * does not want one. Throwing at boot would make that a broken server in their
31
+ * session list; this way it starts, lists its tools, and says plainly what is
32
+ * missing if anybody calls one.
33
+ */
34
+ let client;
35
+ const clientOrThrow = () => {
36
+ // Assigned only on success, so a session that started without a token picks
37
+ // one up on the next call after the file appears — no restart, which matters
38
+ // because a restart is the slowest possible way to learn you got a path
39
+ // wrong. Where the token comes from is lib/token.mjs's problem.
40
+ client ??= makeClient({
41
+ apiUrl: process.env.LOOPABLE_API_URL ?? 'https://api.loopable.ai',
42
+ token: resolveToken(),
43
+ });
44
+ return client;
45
+ };
46
+
47
+ const server = new Server(
48
+ { name: 'loopable', version: '0.1.0' },
49
+ { capabilities: { tools: {} } },
50
+ );
51
+
52
+ server.setRequestHandler(ListToolsRequestSchema, async () => ({
53
+ tools: TOOLS.map((t) => ({
54
+ name: t.name,
55
+ description: t.description,
56
+ inputSchema: t.input,
57
+ })),
58
+ }));
59
+
60
+ server.setRequestHandler(CallToolRequestSchema, async (request) => {
61
+ const { name, arguments: args } = request.params;
62
+ try {
63
+ const result = await runTool(clientOrThrow(), name, args ?? {});
64
+ return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
65
+ } catch (err) {
66
+ // Returned as content rather than thrown, so the model reads the reason
67
+ // and can act on it — "your role does not permit write on approvals" is
68
+ // something to respond to, not a transport failure.
69
+ const message = err instanceof LoopableError ? `${err.status}: ${err.message}` : String(err);
70
+ return { content: [{ type: 'text', text: message }], isError: true };
71
+ }
72
+ });
73
+
74
+ await server.connect(new StdioServerTransport());