@loopable/mcp 0.3.0 → 0.3.8

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,31 @@ for Claude Code; any other MCP host runs it the same way:
13
13
 
14
14
  ## Getting a token in
15
15
 
16
+ Any studio member mints their own in Loopable, from the account menu under
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
20
+ for an agent member under **Settings → Tokens** — an account with no mailbox
21
+ and no password, that can only ever act through a token — and sees and revokes
22
+ everybody's there. Either way the secret is shown once, on the screen that
23
+ mints it, beside these two lines. Then:
24
+
16
25
  ```bash
17
- mkdir -p ~/.config/loopable
18
- printf '%s' 'lpb_…' > ~/.config/loopable/token
26
+ mkdir -p ~/.config/loopable && printf '%s' 'lpb_…' > ~/.config/loopable/token
19
27
  chmod 600 ~/.config/loopable/token
20
28
  ```
21
29
 
30
+ Nothing stores the secret, so losing it means revoking that token and minting
31
+ another — which costs nothing, and is the property that makes a leaked
32
+ database useless.
33
+
22
34
  `.mcp.json` at the repo root registers this server and names **no secret**, so
23
35
  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
36
+ pushing. It launches the server by `git rev-parse --show-toplevel`, not by a
37
+ relative path: Claude Code starts MCP servers in the SESSION's directory, so a
38
+ session started in a subdirectory — `api/`, say — would resolve a relative
39
+ `mcp/server.mjs` to nothing, node dies at import, and
40
+ 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
41
  the next tool call, so dropping it in place does not need a restart.
26
42
 
27
43
  `LOOPABLE_TOKEN` (the value) and `LOOPABLE_TOKEN_FILE` (another path) still win
@@ -30,6 +46,9 @@ unexpanded `${LOOPABLE_TOKEN}` is ignored rather than sent, which is worth a
30
46
  line of code because the alternative is a 401 that blames your credential for
31
47
  your configuration. See `lib/token.mjs`.
32
48
 
49
+ It needs `npm ci` in `mcp/` once per clone: the SDK is its one dependency, and
50
+ without it node dies at import with the same "Connection closed".
51
+
33
52
  Without a token anywhere the server still starts and lists its tools; calling
34
53
  one says how to get one. That is deliberate — everybody working in this repo
35
54
  gets this server, and most of them do not have a token.
@@ -42,17 +61,22 @@ gets this server, and most of them do not have a token.
42
61
  | `next_ready` | what to pick up next — the oldest ready item nobody is on, as a pack |
43
62
  | `pull_item` | the brief pack of one item: the first call of any work session |
44
63
  | `list_backlog` | one project's work items |
64
+ | `get_item` | one item in full: body, brief, children, links, and the trail of every status it has held |
45
65
  | `node` | one node and the edges touching it — the cheapest orientation there is |
46
66
  | `neighbourhood` | what is around a node, one or two hops, filterable by relation |
47
67
  | `path` | how two things relate: the shortest route between them, or none |
68
+ | `list_decisions` | the decisions that stand — superseded ones are history, not guidance |
69
+ | `list_escalations` | the questions waiting on the studio; `resolved` reads the answers |
70
+ | `ask_studio` | put a question to the studio's inbox — the answer comes back on `list_escalations` |
48
71
  | `add_item` | write work into the backlog, under a parent if it has one |
49
72
  | `propose` | put somebody else's ask in the approval queue — **not** in the backlog |
50
73
  | `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 |
52
- | `report_progress` | move an item to todo / in_progress / in_review / blocked / awaiting_input — never done, which is a person's word |
74
+ | `link_items` | say one item blocks another |
75
+ | `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 |
53
77
  | `open_session` | say you have started on an item — opens the live record of this piece of work |
54
78
  | `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` |
79
+ | `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
80
 
57
81
  ## Starting work
58
82
 
@@ -84,10 +108,15 @@ there because you have to name it back: `report_progress`, `open_session`, and
84
108
 
85
109
  **Pulling is not claiming.** `next_ready` is a read, and two harnesses asking
86
110
  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.
111
+ `report_progress` to `in_progress` — and the claim is real: an item carries at
112
+ most one open session, so a second `open_session` on it is a 409 naming the
113
+ session already open. Resume that one, or take other work; never open a
114
+ second.
115
+
116
+ The plugin's `/loopable:start` will do the whole sequence — pull, refuse when
117
+ the item is not `ready` and list its blockers, make the worktree, report and
118
+ open the session — and until it lands, doing it by hand in that order is the
119
+ same thing.
91
120
 
92
121
  `ready_blockers` is the one field to read before anything else. A non-empty
93
122
  list means nobody has groomed the item — there is no criterion carrying a
@@ -96,7 +125,7 @@ work to pick up yet.
96
125
 
97
126
  ## Which kind
98
127
 
99
- Epic, story, task and bug are defined once, in `apps/loopable/VOCABULARY.md`,
128
+ Epic, story, task and bug are defined once, in `VOCABULARY.md` at the repository root,
100
129
  which the Loopable plugin ships as the skill reference
101
130
  `skills/loopable/vocabulary.md` — the same text the product owner's prompt and
102
131
  the in-app Help page read. `add_item` and `propose` quote its rule of thumb in
@@ -128,12 +157,23 @@ disagree with itself. Every hop stands only on nodes the caller may read, so a
128
157
  route that exists only through something they may not see comes back as **no
129
158
  route** rather than as a gap they could infer a secret from.
130
159
 
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.
160
+ **The brief follows the same line, and it used to not.** `write_brief` writes
161
+ the spec straight onto the item when the token holds a studio membership —
162
+ the backlog is the studio's own, and a studio member writing the spec of a
163
+ story the studio decided to build is a member doing their job. It is PROPOSED
164
+ when the ask came from outside that: the product owner drafting for a client,
165
+ and any client-scoped caller, who holds `backlog` read alone. The tool does
166
+ not decide which; it takes the direct path, falls back to the queue on a 403,
167
+ and says which happened — because a copy of `scopes.mjs` living in an npm
168
+ package would be a copy that goes stale the day a role changes.
169
+
170
+ It proposed for everybody until 2026-09-09, on the argument that the brief is
171
+ what readiness and verification are gated on. What that bought in practice was
172
+ nine briefs a night in the studio's own queue, every one written by the
173
+ studio's own developer agent for the studio's own stories — a rubber stamp,
174
+ and the paragraph below says what a queue everybody stamps is worth. Reporting
175
+ where a criterion was implemented and whether it is met was always a direct
176
+ write, and still is: that is progress, not scope.
137
177
 
138
178
  **The backlog and the queue are for different things.** `add_item` writes
139
179
  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 member
49
+ * mints their own 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
+ 'Mint your own in Loopable: account menu → My agent 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,10 @@ 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 ' +
185
+ '(`via_token` true and `token_name` when the move was made through an ' +
186
+ 'agent token rather than by the person’s own hand). ' +
184
187
  'The read to make after list_backlog with titles_only told you which ' +
185
188
  'items matter. `ready_blockers` on the item says why the last readiness ' +
186
189
  'pass would not let it start — a criterion with no verify method, no ' +
@@ -585,7 +588,7 @@ export const TOOLS = [
585
588
  feature_ids: {
586
589
  type: 'array',
587
590
  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.',
591
+ 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
592
  },
590
593
  },
591
594
  required: ['project_id', 'title'],
@@ -700,8 +703,14 @@ export const TOOLS = [
700
703
  type: 'object',
701
704
  properties: {
702
705
  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.' },
706
+ blocker_id: {
707
+ type: 'string',
708
+ description: 'Has to be done first — by id or by ref (41).',
709
+ },
710
+ blocked_id: {
711
+ type: 'string',
712
+ description: 'Cannot start until the blocker is done — by id or by ref (41).',
713
+ },
705
714
  },
706
715
  required: ['project_id', 'blocker_id', 'blocked_id'],
707
716
  additionalProperties: false,
@@ -724,12 +733,15 @@ export const TOOLS = [
724
733
  {
725
734
  name: 'report_progress',
726
735
  /*
727
- * THE ENUM IS THE AGENT'S HALF OF THE TRANSITION TABLE, and it is shorter
728
- * than the API's list on purpose. `ready`, `verifying` and `done` are a
729
- * person's words — grooming, deploying and accepting are seats a person
730
- * sits in — and the API refuses them from a token whatever this file
731
- * offers. Offering them here anyway would only turn a rule into a 403 the
732
- * agent discovers by trying, which is a worse way to learn it.
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. `dropped` is never offered: no
744
+ * token takes it.
733
745
  */
734
746
  description:
735
747
  'Move a work item to todo, in_progress, in_review, blocked or ' +
@@ -740,8 +752,14 @@ export const TOOLS = [
740
752
  'people write it. in_review is as far as you go: a person reads the ' +
741
753
  'diff, merges, and accepts the work as done. Say blocked when something ' +
742
754
  'outside the item is stopping you and awaiting_input when you need an ' +
743
- 'answer — both beat leaving the item claiming work is happening. To ' +
744
- 'change what an item SAYS rather than where it is, use revise.',
755
+ 'answer — both beat leaving the item claiming work is happening. ' +
756
+ 'ready, verifying and done are the person’s, not yours: the API ' +
757
+ 'refuses them unless the person who owns your token minted it with the ' +
758
+ 'grant to set them, and even then you set one ONLY when that person asks ' +
759
+ 'for it in the session and names the items — never on your own judgement ' +
760
+ 'that the work is ready or finished. Such a move is recorded as theirs, ' +
761
+ 'made through your token. To change what an item SAYS rather than where ' +
762
+ 'it is, use revise.',
745
763
  input: {
746
764
  type: 'object',
747
765
  properties: {
@@ -752,7 +770,16 @@ export const TOOLS = [
752
770
  },
753
771
  status: {
754
772
  type: 'string',
755
- enum: ['todo', 'in_progress', 'in_review', 'blocked', 'awaiting_input'],
773
+ enum: [
774
+ 'todo',
775
+ 'in_progress',
776
+ 'in_review',
777
+ 'blocked',
778
+ 'awaiting_input',
779
+ 'ready',
780
+ 'verifying',
781
+ 'done',
782
+ ],
756
783
  },
757
784
  note: {
758
785
  type: 'string',
@@ -781,13 +808,15 @@ export const TOOLS = [
781
808
  'Write the BRIEF of one story, task or bug — the spec, as rows: the ask ' +
782
809
  'as it was actually made, the acceptance criteria each carrying how it ' +
783
810
  '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.',
811
+ 'open. It follows the same line as add_item and propose: the backlog is ' +
812
+ 'the STUDIO\u2019S OWN, so a token holding a studio membership writes the ' +
813
+ 'brief straight onto the item, and a caller from outside that has it ' +
814
+ 'PROPOSED into the approval queue for a person to accept. You do not ' +
815
+ 'choose which — the tool takes the direct path, falls back to the queue ' +
816
+ 'if the API refuses it, and says which happened. Either way the item\u2019s ' +
817
+ 'criteria are replaced whole and its revision bumps. Read the item first ' +
818
+ '(get_item returns the brief) — you are writing the next revision of it, ' +
819
+ 'not adding to it. Never on an epic: an epic is a container.',
791
820
  input: {
792
821
  type: 'object',
793
822
  properties: {
@@ -842,19 +871,58 @@ export const TOOLS = [
842
871
  additionalProperties: false,
843
872
  },
844
873
  /*
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.
874
+ * THE DIRECT PATH FIRST, THE QUEUE AS THE FALLBACK — and no privileged
875
+ * path in either direction. Both calls are the ordinary API carrying the
876
+ * ordinary token; what decides between them is what the token's membership
877
+ * holds, which is `backlog: write` for every studio role and read alone
878
+ * for a client's.
879
+ *
880
+ * THE 403 IS THE ONLY SIGNAL, deliberately. This file does not read the
881
+ * token's memberships and then decide — a second copy of api/lib/scopes.mjs
882
+ * living in an npm package is exactly the drift the whole "no privileged
883
+ * path" argument exists to prevent, and it would be a copy that goes stale
884
+ * the day a role changes. So it tries, and the API's own refusal is what
885
+ * routes it. Any other status is the API's answer and travels unchanged:
886
+ * a 404 on the item must not become a proposal about an item that is not
887
+ * there.
888
+ *
889
+ * The result says which happened, because the caller has to know whether
890
+ * anything is waiting on a person — `written` means it is the spec now,
891
+ * `proposed` means somebody has to accept it before readiness will read it.
892
+ * `title` belongs to the queue's line and not to the spec, which is why the
893
+ * direct write never sends it.
848
894
  */
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
- }),
895
+ run: async (client, { project_id, item_id, title, ...brief }) => {
896
+ const project = encodeURIComponent(project_id);
897
+ try {
898
+ const { brief: written } = await client.call(
899
+ `/agent/projects/${project}/items/${encodeURIComponent(item_id)}/brief`,
900
+ { method: 'PUT', body: JSON.stringify(brief) },
901
+ );
902
+ return {
903
+ written: true,
904
+ how: 'written directly — the studio\u2019s own backlog, so nothing is waiting on a person',
905
+ brief: written,
906
+ };
907
+ } catch (err) {
908
+ if (!(err instanceof LoopableError) || err.status !== 403) throw err;
909
+ const { draft } = await client.call(`/agent/projects/${project}/drafts`, {
910
+ method: 'POST',
911
+ body: JSON.stringify({
912
+ title,
913
+ proposal_type: 'brief',
914
+ // The kind rides the default ('story'): approving a brief creates
915
+ // nothing, it writes onto the item the payload names.
916
+ payload: { item_id, ...brief },
917
+ }),
918
+ });
919
+ return {
920
+ proposed: true,
921
+ how: `proposed — this token may not write the backlog here (${err.message}), so a person accepts it first`,
922
+ draft,
923
+ };
924
+ }
925
+ },
858
926
  },
859
927
 
860
928
  /*
@@ -876,7 +944,11 @@ export const TOOLS = [
876
944
  'live record of this piece of work — the console and the product owner ' +
877
945
  'both read it. Do it once, when you start, and keep the id: ' +
878
946
  '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.',
947
+ 'repo and which branch, so a person watching can find what you are doing. ' +
948
+ 'ONE SESSION PER ITEM: if somebody already has one open on it the answer ' +
949
+ 'is a 409 naming that session — pulling an item is not claiming it, and ' +
950
+ 'the claim is this call. Resume the session it names, or work on ' +
951
+ 'something else; never open a second.',
880
952
  input: {
881
953
  type: 'object',
882
954
  properties: {
@@ -964,7 +1036,9 @@ export const TOOLS = [
964
1036
  'screenshot_ids and cost are all required, a missing one is a 422 that ' +
965
1037
  'names every field you left out, and the item stays in_progress until ' +
966
1038
  '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.',
1039
+ 'in_review for you; an "error" close owes none of it and moves nothing. ' +
1040
+ 'If there is a pull request, open it first and pass pr_url: the close is ' +
1041
+ 'the only write a session ever gets, and nothing can add the link later.',
968
1042
  input: {
969
1043
  type: 'object',
970
1044
  properties: {
@@ -1051,6 +1125,17 @@ export const TOOLS = [
1051
1125
  },
1052
1126
  required: ['tokens', 'usd'],
1053
1127
  },
1128
+ pr_url: {
1129
+ type: 'string',
1130
+ description:
1131
+ 'OPTIONAL, and the only optional part of a complete close: the pull ' +
1132
+ 'request this work went into, as an http(s) url. Open it BEFORE you ' +
1133
+ 'close and name it here — a closed session is never updated again, so ' +
1134
+ 'this is the only moment the link can be recorded. Leave it out when ' +
1135
+ 'there genuinely is no pull request; a made-up or half-typed url is a ' +
1136
+ '422, because a link somebody clicks and lands nowhere is worse than no ' +
1137
+ 'link. The number is read out of the url for you.',
1138
+ },
1054
1139
  },
1055
1140
  required: ['project_id', 'session_id', 'state'],
1056
1141
  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.8",
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",