@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 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. The token lives in a file only you can read; the server picks it up on
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` | propose the spec of one item — the ask, the acceptance criteria, what is out of scope |
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`. The plugin's `/loopable:start` will do the
88
- whole sequence — pull, refuse when the item is not `ready` and list its
89
- blockers, make the worktree, report and open the session — and until it lands,
90
- doing it by hand in that order is the same thing.
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 is the exception, and it is the interesting one.** `write_brief`
132
- proposes even though the same token could `add_item` — because the brief is
133
- what readiness and verification are gated on, and a spec nobody agreed to is a
134
- bar the agent set for itself. Reporting where a criterion was implemented and
135
- whether it is met goes the other way: that is progress, not scope, and it is a
136
- direct write.
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
- `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(' ');
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, and the dependency links touching it. ' +
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 — ids from list_backlog (their refs, plain numbers like 7, are for people; this list takes ids). One is usual, several is legal, none is fine.',
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: { type: 'string', description: 'Has to be done first.' },
704
- blocked_id: { type: 'string', description: 'Cannot start until the blocker is done.' },
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 goes to the approval queue: unlike add_item, a brief is ' +
785
- 'PROPOSED even by an agent that could write the backlog directly, ' +
786
- 'because the brief is what readiness and verification are gated on and a ' +
787
- 'person has to have agreed to it. Approving replaces the item’s criteria ' +
788
- 'whole and bumps its revision. Read the item first (get_item returns the ' +
789
- 'brief) — you are writing the next revision of it, not adding to it. ' +
790
- 'Never on an epic: an epic is a container.',
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
- * A draft, through the ordinary proposals door — no privileged path here
846
- * either. The kind rides the default ('story'): approving a brief creates
847
- * nothing, it writes onto the item the payload names.
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
- client.call(`/agent/projects/${encodeURIComponent(project_id)}/drafts`, {
851
- method: 'POST',
852
- body: JSON.stringify({
853
- title,
854
- proposal_type: 'brief',
855
- payload: { item_id, ...brief },
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.0",
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",