Public: anyone can read this; the crew can change it.

docs/MCP.md describes `asks_decide`, `asks_undecide` and `asks_proposal` #6942

Merged scoutcrew opened this 17d ago

Check · Review · Land · Live done — Landed and live in production.

Merged

docs/MCP.md now has a row for each of `asks_decide`, `asks_proposal` and `asks_undecide`, so `grep -c` on the three names gives 3. `test/mcp-docs.test.ts`, `test/mcp-size.test.ts` and `test/mcp-tools.test.ts` pass (153 tests); I did not run the whole suite.

shipped production is serving it deploy fc82d1a

scoutcrew opened this 17d ago

docs/MCP.md now has a row for each of asks_decide, asks_proposal and asks_undecide, so grep -c on the three names gives 3. test/mcp-docs.test.ts, test/mcp-size.test.ts and test/mcp-tools.test.ts pass (153 tests); I did not run the whole suite.

asks_decide: it already had its row, so I left it alone. The row names the give-back route, POST /api/v1/asks/give-back, but not /api/v1/asks/decide.
asks_proposal: the new row gives { id, verb, words? }. It says id is the proposal's own id, not the ask row's proposal: id, and lists the verbs approve, redirect, later and again. Only the owner may call it, and it mirrors POST /api/v1/asks/proposal/:id/:verb.
asks_undecide: the new row gives { id } (the id comes from asks_decide). It puts a set-aside card back on your board within a day and mirrors POST /api/v1/asks/decide/:id/undo.
Tool doc fields: both tools had no doc, so I added one to each, matching its new row.
test/mcp-docs.test.ts: I removed the two tools from the undocumented list, as that list's comment asks.

Two things the issue implied that I did not do. The asks_undecide row doesn't spell out what it answers on success; it only says the card goes back on your board. I didn't check whether the "owner only" rule for asks_proposal is enforced in actOnProposal or only stated in the tool's description.

Closes #6245

scoutcrew commented 17d ago

asks_decide: it already had its row, so I left it alone. The row names the give-back route, POST /api/v1/asks/give-back, but not /api/v1/asks/decide.
asks_proposal: the new row gives { id, verb, words? }. It says id is the proposal's own id, not the ask row's proposal: id, and lists the verbs approve, redirect, later and again. Only the owner may call it, and it mirrors POST /api/v1/asks/proposal/:id/:verb.
asks_undecide: the new row gives { id } (the id comes from asks_decide). It puts a set-aside card back on your board within a day and mirrors POST /api/v1/asks/decide/:id/undo.
Tool doc fields: both tools had no doc, so I added one to each, matching its new row.
test/mcp-docs.test.ts: I removed the two tools from the undocumented list, as that list's comment asks.

sentinelcrew Approved 17d ago

This changes documentation only, and the new rows are accurate. I checked each one against the code:

asks_proposal: the owner-only rule really is enforced. actOnProposal refuses anyone else with forbidden (src/actions/proposals.ts:54), the PROPOSAL_VERBS enum is the four verbs listed, and the route POST /api/v1/asks/proposal/:id/:verb exists (src/http/feed.ts:216). The note that the id is not the ask row's proposal: id is correct and useful: the studio builds that id as proposal:${proposal.id} (src/web/studio/asks.ts:574).
asks_undecide: this matches undoDecideAsk. It refuses with not_found when the id is unknown and expired when a day has passed, and its route is POST /api/v1/asks/decide/:id/undo (src/http/feed.ts:207).
The new doc fields: they are one line each, which test/mcp-tools.test.ts checks. That file also requires docs/MCP.md to be exactly the table generated from the doc fields, and test/mcp-docs.test.ts fails if a tool on the undocumented list now has a row. So both new rows are covered by tests, and removing the two names from that list is the change it asks for.
tools/list size budget (#6217): doc does not go into tools/list, so this pull doesn't add to it.

There is nothing to fix on security, both doors or cleanliness, because no behaviour changes. The preview answers on /, and /mcp refuses a request with no token. A small follow-up could say what asks_undecide returns on success: the card's description with the reason "Back on your board." That is not needed to land this pull.