@loopable/mcp 0.3.0 → 0.3.6
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 +44 -15
- package/lib/token.mjs +19 -4
- package/lib/tools.mjs +90 -25
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -13,15 +13,28 @@ for Claude Code; any other MCP host runs it the same way:
|
|
|
13
13
|
|
|
14
14
|
## Getting a token in
|
|
15
15
|
|
|
16
|
+
A studio admin mints one in Loopable, under **Settings → Tokens**, picking the
|
|
17
|
+
agent member it acts as — or creating one there, which is what an agent needs:
|
|
18
|
+
an account with no mailbox and no password, that can only ever act through a
|
|
19
|
+
token. The secret is shown once, on the screen that mints it, beside these two
|
|
20
|
+
lines. Then:
|
|
21
|
+
|
|
16
22
|
```bash
|
|
17
|
-
mkdir -p ~/.config/loopable
|
|
18
|
-
printf '%s' 'lpb_…' > ~/.config/loopable/token
|
|
23
|
+
mkdir -p ~/.config/loopable && printf '%s' 'lpb_…' > ~/.config/loopable/token
|
|
19
24
|
chmod 600 ~/.config/loopable/token
|
|
20
25
|
```
|
|
21
26
|
|
|
27
|
+
Nothing stores the secret, so losing it means revoking that token and minting
|
|
28
|
+
another — which costs nothing, and is the property that makes a leaked
|
|
29
|
+
database useless.
|
|
30
|
+
|
|
22
31
|
`.mcp.json` at the repo root registers this server and names **no secret**, so
|
|
23
32
|
there is nothing in a tracked file to leak and nothing to redact before
|
|
24
|
-
pushing.
|
|
33
|
+
pushing. It launches the server by `git rev-parse --show-toplevel`, not by a
|
|
34
|
+
relative path: Claude Code starts MCP servers in the SESSION's directory, and
|
|
35
|
+
`platform/bin/dispatch.sh` starts every app agent in `apps/<app>` — where a
|
|
36
|
+
relative `apps/loopable/mcp/server.mjs` names nothing, node dies at import, and
|
|
37
|
+
all the session ever says is "Connection closed". The token lives in a file only you can read; the server picks it up on
|
|
25
38
|
the next tool call, so dropping it in place does not need a restart.
|
|
26
39
|
|
|
27
40
|
`LOOPABLE_TOKEN` (the value) and `LOOPABLE_TOKEN_FILE` (another path) still win
|
|
@@ -48,11 +61,11 @@ gets this server, and most of them do not have a token.
|
|
|
48
61
|
| `add_item` | write work into the backlog, under a parent if it has one |
|
|
49
62
|
| `propose` | put somebody else's ask in the approval queue — **not** in the backlog |
|
|
50
63
|
| `revise` | correct an item's title or body |
|
|
51
|
-
| `write_brief` |
|
|
64
|
+
| `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 |
|
|
52
65
|
| `report_progress` | move an item to todo / in_progress / in_review / blocked / awaiting_input — never done, which is a person's word |
|
|
53
66
|
| `open_session` | say you have started on an item — opens the live record of this piece of work |
|
|
54
67
|
| `post_activity` | one line into an open session: thought, action, question, result or error |
|
|
55
|
-
| `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 moves the item to `in_review` |
|
|
68
|
+
| `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` |
|
|
56
69
|
|
|
57
70
|
## Starting work
|
|
58
71
|
|
|
@@ -84,10 +97,15 @@ there because you have to name it back: `report_progress`, `open_session`, and
|
|
|
84
97
|
|
|
85
98
|
**Pulling is not claiming.** `next_ready` is a read, and two harnesses asking
|
|
86
99
|
in the same second are told the same item. Claiming is `open_session` and
|
|
87
|
-
`report_progress` to `in_progress
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
100
|
+
`report_progress` to `in_progress` — and the claim is real: an item carries at
|
|
101
|
+
most one open session, so a second `open_session` on it is a 409 naming the
|
|
102
|
+
session already open. Resume that one, or take other work; never open a
|
|
103
|
+
second.
|
|
104
|
+
|
|
105
|
+
The plugin's `/loopable:start` will do the whole sequence — pull, refuse when
|
|
106
|
+
the item is not `ready` and list its blockers, make the worktree, report and
|
|
107
|
+
open the session — and until it lands, doing it by hand in that order is the
|
|
108
|
+
same thing.
|
|
91
109
|
|
|
92
110
|
`ready_blockers` is the one field to read before anything else. A non-empty
|
|
93
111
|
list means nobody has groomed the item — there is no criterion carrying a
|
|
@@ -128,12 +146,23 @@ disagree with itself. Every hop stands only on nodes the caller may read, so a
|
|
|
128
146
|
route that exists only through something they may not see comes back as **no
|
|
129
147
|
route** rather than as a gap they could infer a secret from.
|
|
130
148
|
|
|
131
|
-
**The brief
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
149
|
+
**The brief follows the same line, and it used to not.** `write_brief` writes
|
|
150
|
+
the spec straight onto the item when the token holds a studio membership —
|
|
151
|
+
the backlog is the studio's own, and a studio member writing the spec of a
|
|
152
|
+
story the studio decided to build is a member doing their job. It is PROPOSED
|
|
153
|
+
when the ask came from outside that: the product owner drafting for a client,
|
|
154
|
+
and any client-scoped caller, who holds `backlog` read alone. The tool does
|
|
155
|
+
not decide which; it takes the direct path, falls back to the queue on a 403,
|
|
156
|
+
and says which happened — because a copy of `scopes.mjs` living in an npm
|
|
157
|
+
package would be a copy that goes stale the day a role changes.
|
|
158
|
+
|
|
159
|
+
It proposed for everybody until 2026-09-09, on the argument that the brief is
|
|
160
|
+
what readiness and verification are gated on. What that bought in practice was
|
|
161
|
+
nine briefs a night in the studio's own queue, every one written by the
|
|
162
|
+
studio's own developer agent for the studio's own stories — a rubber stamp,
|
|
163
|
+
and the paragraph below says what a queue everybody stamps is worth. Reporting
|
|
164
|
+
where a criterion was implemented and whether it is met was always a direct
|
|
165
|
+
write, and still is: that is progress, not scope.
|
|
137
166
|
|
|
138
167
|
**The backlog and the queue are for different things.** `add_item` writes
|
|
139
168
|
straight into the backlog; `propose` puts a draft in the approval queue for a
|
package/lib/token.mjs
CHANGED
|
@@ -38,12 +38,27 @@ const clean = (value) => {
|
|
|
38
38
|
return token && !unexpanded(token) ? token : null;
|
|
39
39
|
};
|
|
40
40
|
|
|
41
|
+
/**
|
|
42
|
+
* What a person reads at the one moment they have no credential.
|
|
43
|
+
*
|
|
44
|
+
* It used to name `POST /v1/studios/<studio-id>/agent-tokens`, a route that
|
|
45
|
+
* has never existed — the real one is `.../tokens` — so the message sent the
|
|
46
|
+
* reader to a 404 at exactly the moment they had nothing else to go on. The
|
|
47
|
+
* fix is not a corrected path: a path hand-copied into a string is a path that
|
|
48
|
+
* drifts again the next time the route moves. It names the SCREEN a studio
|
|
49
|
+
* admin mints a token on, and then the two lines that put the secret where
|
|
50
|
+
* this module will look for it.
|
|
51
|
+
*/
|
|
41
52
|
export const NO_TOKEN = [
|
|
42
53
|
'No Loopable token.',
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
'
|
|
46
|
-
|
|
54
|
+
'',
|
|
55
|
+
`Put one in ~/${DEFAULT_TOKEN_FILE} (chmod 600), or set LOOPABLE_TOKEN_FILE to where you keep it.`,
|
|
56
|
+
'A studio admin mints one in Loopable, under Settings → Tokens; the secret is shown once.',
|
|
57
|
+
'Then, on this machine:',
|
|
58
|
+
'',
|
|
59
|
+
` printf '%s' 'lpb_…' > ~/${DEFAULT_TOKEN_FILE}`,
|
|
60
|
+
` chmod 600 ~/${DEFAULT_TOKEN_FILE}`,
|
|
61
|
+
].join('\n');
|
|
47
62
|
|
|
48
63
|
/**
|
|
49
64
|
* @param env process.env, or a stand-in
|
package/lib/tools.mjs
CHANGED
|
@@ -180,7 +180,8 @@ export const TOOLS = [
|
|
|
180
180
|
name: 'get_item',
|
|
181
181
|
description:
|
|
182
182
|
'One work item in full: its body, its brief (the ask and the acceptance ' +
|
|
183
|
-
'criteria), its children by title,
|
|
183
|
+
'criteria), its children by title, the dependency links touching it, and ' +
|
|
184
|
+
'`trail`: every status it has held, oldest first, with who moved it. ' +
|
|
184
185
|
'The read to make after list_backlog with titles_only told you which ' +
|
|
185
186
|
'items matter. `ready_blockers` on the item says why the last readiness ' +
|
|
186
187
|
'pass would not let it start — a criterion with no verify method, no ' +
|
|
@@ -585,7 +586,7 @@ export const TOOLS = [
|
|
|
585
586
|
feature_ids: {
|
|
586
587
|
type: 'array',
|
|
587
588
|
items: { type: 'string' },
|
|
588
|
-
description: 'The features (surfaces) this work touches —
|
|
589
|
+
description: 'The features (surfaces) this work touches — by id or ref (7), from list_backlog. One is usual, several is legal, none is fine.',
|
|
589
590
|
},
|
|
590
591
|
},
|
|
591
592
|
required: ['project_id', 'title'],
|
|
@@ -700,8 +701,14 @@ export const TOOLS = [
|
|
|
700
701
|
type: 'object',
|
|
701
702
|
properties: {
|
|
702
703
|
project_id: { type: 'string', description: 'From whoami.' },
|
|
703
|
-
blocker_id: {
|
|
704
|
-
|
|
704
|
+
blocker_id: {
|
|
705
|
+
type: 'string',
|
|
706
|
+
description: 'Has to be done first — by id or by ref (41).',
|
|
707
|
+
},
|
|
708
|
+
blocked_id: {
|
|
709
|
+
type: 'string',
|
|
710
|
+
description: 'Cannot start until the blocker is done — by id or by ref (41).',
|
|
711
|
+
},
|
|
705
712
|
},
|
|
706
713
|
required: ['project_id', 'blocker_id', 'blocked_id'],
|
|
707
714
|
additionalProperties: false,
|
|
@@ -781,13 +788,15 @@ export const TOOLS = [
|
|
|
781
788
|
'Write the BRIEF of one story, task or bug — the spec, as rows: the ask ' +
|
|
782
789
|
'as it was actually made, the acceptance criteria each carrying how it ' +
|
|
783
790
|
'will be checked, what is out of scope, what you assumed, what is still ' +
|
|
784
|
-
'open. It
|
|
785
|
-
'
|
|
786
|
-
'
|
|
787
|
-
'
|
|
788
|
-
'
|
|
789
|
-
'
|
|
790
|
-
'
|
|
791
|
+
'open. It follows the same line as add_item and propose: the backlog is ' +
|
|
792
|
+
'the STUDIO\u2019S OWN, so a token holding a studio membership writes the ' +
|
|
793
|
+
'brief straight onto the item, and a caller from outside that has it ' +
|
|
794
|
+
'PROPOSED into the approval queue for a person to accept. You do not ' +
|
|
795
|
+
'choose which — the tool takes the direct path, falls back to the queue ' +
|
|
796
|
+
'if the API refuses it, and says which happened. Either way the item\u2019s ' +
|
|
797
|
+
'criteria are replaced whole and its revision bumps. Read the item first ' +
|
|
798
|
+
'(get_item returns the brief) — you are writing the next revision of it, ' +
|
|
799
|
+
'not adding to it. Never on an epic: an epic is a container.',
|
|
791
800
|
input: {
|
|
792
801
|
type: 'object',
|
|
793
802
|
properties: {
|
|
@@ -842,19 +851,58 @@ export const TOOLS = [
|
|
|
842
851
|
additionalProperties: false,
|
|
843
852
|
},
|
|
844
853
|
/*
|
|
845
|
-
*
|
|
846
|
-
* either.
|
|
847
|
-
*
|
|
854
|
+
* THE DIRECT PATH FIRST, THE QUEUE AS THE FALLBACK — and no privileged
|
|
855
|
+
* path in either direction. Both calls are the ordinary API carrying the
|
|
856
|
+
* ordinary token; what decides between them is what the token's membership
|
|
857
|
+
* holds, which is `backlog: write` for every studio role and read alone
|
|
858
|
+
* for a client's.
|
|
859
|
+
*
|
|
860
|
+
* THE 403 IS THE ONLY SIGNAL, deliberately. This file does not read the
|
|
861
|
+
* token's memberships and then decide — a second copy of api/lib/scopes.mjs
|
|
862
|
+
* living in an npm package is exactly the drift the whole "no privileged
|
|
863
|
+
* path" argument exists to prevent, and it would be a copy that goes stale
|
|
864
|
+
* the day a role changes. So it tries, and the API's own refusal is what
|
|
865
|
+
* routes it. Any other status is the API's answer and travels unchanged:
|
|
866
|
+
* a 404 on the item must not become a proposal about an item that is not
|
|
867
|
+
* there.
|
|
868
|
+
*
|
|
869
|
+
* The result says which happened, because the caller has to know whether
|
|
870
|
+
* anything is waiting on a person — `written` means it is the spec now,
|
|
871
|
+
* `proposed` means somebody has to accept it before readiness will read it.
|
|
872
|
+
* `title` belongs to the queue's line and not to the spec, which is why the
|
|
873
|
+
* direct write never sends it.
|
|
848
874
|
*/
|
|
849
|
-
run: (client, { project_id, item_id, title, ...brief }) =>
|
|
850
|
-
|
|
851
|
-
|
|
852
|
-
|
|
853
|
-
|
|
854
|
-
|
|
855
|
-
|
|
856
|
-
|
|
857
|
-
|
|
875
|
+
run: async (client, { project_id, item_id, title, ...brief }) => {
|
|
876
|
+
const project = encodeURIComponent(project_id);
|
|
877
|
+
try {
|
|
878
|
+
const { brief: written } = await client.call(
|
|
879
|
+
`/agent/projects/${project}/items/${encodeURIComponent(item_id)}/brief`,
|
|
880
|
+
{ method: 'PUT', body: JSON.stringify(brief) },
|
|
881
|
+
);
|
|
882
|
+
return {
|
|
883
|
+
written: true,
|
|
884
|
+
how: 'written directly — the studio\u2019s own backlog, so nothing is waiting on a person',
|
|
885
|
+
brief: written,
|
|
886
|
+
};
|
|
887
|
+
} catch (err) {
|
|
888
|
+
if (!(err instanceof LoopableError) || err.status !== 403) throw err;
|
|
889
|
+
const { draft } = await client.call(`/agent/projects/${project}/drafts`, {
|
|
890
|
+
method: 'POST',
|
|
891
|
+
body: JSON.stringify({
|
|
892
|
+
title,
|
|
893
|
+
proposal_type: 'brief',
|
|
894
|
+
// The kind rides the default ('story'): approving a brief creates
|
|
895
|
+
// nothing, it writes onto the item the payload names.
|
|
896
|
+
payload: { item_id, ...brief },
|
|
897
|
+
}),
|
|
898
|
+
});
|
|
899
|
+
return {
|
|
900
|
+
proposed: true,
|
|
901
|
+
how: `proposed — this token may not write the backlog here (${err.message}), so a person accepts it first`,
|
|
902
|
+
draft,
|
|
903
|
+
};
|
|
904
|
+
}
|
|
905
|
+
},
|
|
858
906
|
},
|
|
859
907
|
|
|
860
908
|
/*
|
|
@@ -876,7 +924,11 @@ export const TOOLS = [
|
|
|
876
924
|
'live record of this piece of work — the console and the product owner ' +
|
|
877
925
|
'both read it. Do it once, when you start, and keep the id: ' +
|
|
878
926
|
'post_activity and close_session both need it. Say which harness, which ' +
|
|
879
|
-
'repo and which branch, so a person watching can find what you are doing.'
|
|
927
|
+
'repo and which branch, so a person watching can find what you are doing. ' +
|
|
928
|
+
'ONE SESSION PER ITEM: if somebody already has one open on it the answer ' +
|
|
929
|
+
'is a 409 naming that session — pulling an item is not claiming it, and ' +
|
|
930
|
+
'the claim is this call. Resume the session it names, or work on ' +
|
|
931
|
+
'something else; never open a second.',
|
|
880
932
|
input: {
|
|
881
933
|
type: 'object',
|
|
882
934
|
properties: {
|
|
@@ -964,7 +1016,9 @@ export const TOOLS = [
|
|
|
964
1016
|
'screenshot_ids and cost are all required, a missing one is a 422 that ' +
|
|
965
1017
|
'names every field you left out, and the item stays in_progress until ' +
|
|
966
1018
|
'you send them. A successful "complete" close moves the item to ' +
|
|
967
|
-
'in_review for you; an "error" close owes none of it and moves nothing.'
|
|
1019
|
+
'in_review for you; an "error" close owes none of it and moves nothing. ' +
|
|
1020
|
+
'If there is a pull request, open it first and pass pr_url: the close is ' +
|
|
1021
|
+
'the only write a session ever gets, and nothing can add the link later.',
|
|
968
1022
|
input: {
|
|
969
1023
|
type: 'object',
|
|
970
1024
|
properties: {
|
|
@@ -1051,6 +1105,17 @@ export const TOOLS = [
|
|
|
1051
1105
|
},
|
|
1052
1106
|
required: ['tokens', 'usd'],
|
|
1053
1107
|
},
|
|
1108
|
+
pr_url: {
|
|
1109
|
+
type: 'string',
|
|
1110
|
+
description:
|
|
1111
|
+
'OPTIONAL, and the only optional part of a complete close: the pull ' +
|
|
1112
|
+
'request this work went into, as an http(s) url. Open it BEFORE you ' +
|
|
1113
|
+
'close and name it here — a closed session is never updated again, so ' +
|
|
1114
|
+
'this is the only moment the link can be recorded. Leave it out when ' +
|
|
1115
|
+
'there genuinely is no pull request; a made-up or half-typed url is a ' +
|
|
1116
|
+
'422, because a link somebody clicks and lands nowhere is worse than no ' +
|
|
1117
|
+
'link. The number is read out of the url for you.',
|
|
1118
|
+
},
|
|
1054
1119
|
},
|
|
1055
1120
|
required: ['project_id', 'session_id', 'state'],
|
|
1056
1121
|
additionalProperties: false,
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@loopable/mcp",
|
|
3
|
-
"version": "0.3.
|
|
3
|
+
"version": "0.3.6",
|
|
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",
|