@loopable/mcp 0.3.6 → 0.3.9

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,11 +13,14 @@ 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:
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:
21
24
 
22
25
  ```bash
23
26
  mkdir -p ~/.config/loopable && printf '%s' 'lpb_…' > ~/.config/loopable/token
@@ -31,9 +34,9 @@ database useless.
31
34
  `.mcp.json` at the repo root registers this server and names **no secret**, so
32
35
  there is nothing in a tracked file to leak and nothing to redact before
33
36
  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
+ 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
37
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
38
41
  the next tool call, so dropping it in place does not need a restart.
39
42
 
@@ -43,6 +46,9 @@ unexpanded `${LOOPABLE_TOKEN}` is ignored rather than sent, which is worth a
43
46
  line of code because the alternative is a 401 that blames your credential for
44
47
  your configuration. See `lib/token.mjs`.
45
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
+
46
52
  Without a token anywhere the server still starts and lists its tools; calling
47
53
  one says how to get one. That is deliberate — everybody working in this repo
48
54
  gets this server, and most of them do not have a token.
@@ -55,14 +61,19 @@ gets this server, and most of them do not have a token.
55
61
  | `next_ready` | what to pick up next — the oldest ready item nobody is on, as a pack |
56
62
  | `pull_item` | the brief pack of one item: the first call of any work session |
57
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 |
58
65
  | `node` | one node and the edges touching it — the cheapest orientation there is |
59
66
  | `neighbourhood` | what is around a node, one or two hops, filterable by relation |
60
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` |
61
71
  | `add_item` | write work into the backlog, under a parent if it has one |
62
72
  | `propose` | put somebody else's ask in the approval queue — **not** in the backlog |
63
73
  | `revise` | correct an item's title or body |
74
+ | `link_items` | say one item blocks another |
64
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 |
65
- | `report_progress` | move an item to todo / in_progress / in_review / blocked / awaiting_input — never done, which is a person's word |
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 |
66
77
  | `open_session` | say you have started on an item — opens the live record of this piece of work |
67
78
  | `post_activity` | one line into an open session: thought, action, question, result or error |
68
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` |
@@ -114,7 +125,7 @@ work to pick up yet.
114
125
 
115
126
  ## Which kind
116
127
 
117
- 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,
118
129
  which the Loopable plugin ships as the skill reference
119
130
  `skills/loopable/vocabulary.md` — the same text the product owner's prompt and
120
131
  the in-app Help page read. `add_item` and `propose` quote its rule of thumb in
package/lib/token.mjs CHANGED
@@ -45,15 +45,15 @@ const clean = (value) => {
45
45
  * has never existed — the real one is `.../tokens` — so the message sent the
46
46
  * reader to a 404 at exactly the moment they had nothing else to go on. The
47
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
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
50
  * this module will look for it.
51
51
  */
52
52
  export const NO_TOKEN = [
53
53
  'No Loopable token.',
54
54
  '',
55
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.',
56
+ 'Mint your own in Loopable: account menu → My agent tokens; the secret is shown once.',
57
57
  'Then, on this machine:',
58
58
  '',
59
59
  ` printf '%s' 'lpb_…' > ~/${DEFAULT_TOKEN_FILE}`,
package/lib/tools.mjs CHANGED
@@ -181,7 +181,9 @@ export const TOOLS = [
181
181
  description:
182
182
  'One work item in full: its body, its brief (the ask and the acceptance ' +
183
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
+ '`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). ' +
185
187
  'The read to make after list_backlog with titles_only told you which ' +
186
188
  'items matter. `ready_blockers` on the item says why the last readiness ' +
187
189
  'pass would not let it start — a criterion with no verify method, no ' +
@@ -731,12 +733,15 @@ export const TOOLS = [
731
733
  {
732
734
  name: 'report_progress',
733
735
  /*
734
- * THE ENUM IS THE AGENT'S HALF OF THE TRANSITION TABLE, and it is shorter
735
- * than the API's list on purpose. `ready`, `verifying` and `done` are a
736
- * person's words — grooming, deploying and accepting are seats a person
737
- * sits in — and the API refuses them from a token whatever this file
738
- * offers. Offering them here anyway would only turn a rule into a 403 the
739
- * 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.
740
745
  */
741
746
  description:
742
747
  'Move a work item to todo, in_progress, in_review, blocked or ' +
@@ -747,8 +752,14 @@ export const TOOLS = [
747
752
  'people write it. in_review is as far as you go: a person reads the ' +
748
753
  'diff, merges, and accepts the work as done. Say blocked when something ' +
749
754
  'outside the item is stopping you and awaiting_input when you need an ' +
750
- 'answer — both beat leaving the item claiming work is happening. To ' +
751
- '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.',
752
763
  input: {
753
764
  type: 'object',
754
765
  properties: {
@@ -759,7 +770,16 @@ export const TOOLS = [
759
770
  },
760
771
  status: {
761
772
  type: 'string',
762
- 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
+ ],
763
783
  },
764
784
  note: {
765
785
  type: 'string',
@@ -962,7 +982,10 @@ export const TOOLS = [
962
982
  'go rather than in a batch at the end — a session with no activity for a ' +
963
983
  'while reads as stalled, and that is the point of it. A `question` puts ' +
964
984
  'the session in awaiting_input; to actually ASK the studio something and ' +
965
- 'get an answer back, use ask_studio.',
985
+ 'get an answer back, use ask_studio. A CLOSED session takes activities ' +
986
+ 'from the member who held it and nobody else — what was decided after ' +
987
+ 'the close, on the verdict it closed with — and the post changes nothing ' +
988
+ 'about its ending: state, closed_at and the contract stay as they were.',
966
989
  input: {
967
990
  type: 'object',
968
991
  properties: {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@loopable/mcp",
3
- "version": "0.3.6",
3
+ "version": "0.3.9",
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",