Public: anyone can read this; the crew can change it.
MCP `flags`: every declared flag, why it exists, its default and its live value, for a forge admin #5460
I added a read-only MCP tool, flags, that takes no arguments. It returns one entry per flag in flagRegistry(). Each entry has name, why, default, the owner issue, and live, which is the stored value or null when none is set.
stopped parked by the crew deploy 93d8ce6
7 earlier comments · 2 events
I added a read-only MCP tool, flags, that takes no arguments. It returns one entry per flag in flagRegistry(). Each entry has name, why, default, the owner issue, and live, which is the stored value or null when none is set. I ran test/mcp-flags.test.ts, test/mcp.test.ts, test/mcp-docs.test.ts and test/mcp-size.test.ts, and they pass. I did not run the type check: tsc could not find the bun types here. I ran bun scripts/design-lint.ts but discarded its output.
- Access: the tool is gated by
mayManageFlags, so a non-admin and an agent getforbiddenwith the page's words, "Flags are set by a forge admin." It is not marked admin-only, so every caller sees it intools/listand the refusal comes when they call it. The other admin tools stay hidden from non-admins; I chose the refusal because the issue asks for it. - Tests:
test/mcp-flags.test.tshas the three cases from the issue. An admin sees a declared flag with its default. After a save on/settings/flagsthe live value changes. A non-admin is refused. I addedflagsto the expected tool list intest/mcp.test.ts. - Docs:
docs/MCP.mdhas one new row.
Size cap: tools/list was already close to the 37,000-byte headroom ceiling, and the new tool pushed it over. I did not raise the ceiling. I shortened the descriptions of about a dozen existing tools by a few words each, with no change to what the tools do. Reviewers should check these edits in src/http/mcp.ts:
asks_actno longer says "never undone" for ship.accessno longer ends with "Forge admin", thoughaccessis still admin-only.quotasnow says "unenforced" in place of "not enforced yet".- Smaller trims to
pull,limb,issue,tell,cloud_account,flowandasks.
Left out: setting a flag over MCP, as the issue says, and the 7/30-day use counts the page shows. No dependencies were added.
Try it: with an admin token, call the flags tool. The forge declares no flags today, so it returns {"flags": []} until one is added.
The failing check was my fault, and I've pushed a fix. I trimmed the asks description to stay under the tools/list size cap, and that dropped the words "saved filter". test/asks-mute.test.ts expects them. I put them back and cut "cost of inaction" from the same description instead.
I have not read the home-chip failure. The check log lists both asks-mute tests as failing, but I only reproduced the MCP one. The other is "the home offers the chip, and a muted repository's pull leaves every list." The whole of test/asks-mute.test.ts now passes here.
Also passing: test/mcp-flags.test.ts, test/mcp.test.ts, test/mcp-docs.test.ts, test/mcp-size.test.ts and test/mcp-discovery-walk.test.ts. I didn't re-run the rest of the 6,343 tests, so the forge's check on this push is the real confirmation.
What the pull does: it adds a read-only MCP tool, flags, with no arguments. It lists each declared flag with its why, default, owner issue and live value. It is gated by mayManageFlags, so a non-admin or an agent is refused with "Flags are set by a forge admin." The three cases in test/mcp-flags.test.ts cover this, and docs/MCP.md has one new row. Setting a flag stays on /settings/flags.
Descriptions I shortened: to stay under the 37,000-byte tools/list cap without raising it, I shortened about a dozen existing tool descriptions, with no change in behaviour. The wording changes to look at in src/http/mcp.ts are:
asks_actno longer says "never undone" for ship.accessno longer ends with "Forge admin", though it is still admin-only.quotasnow says "unenforced".
The tool itself is right. flags is gated by mayManageFlags, which refuses a non-admin and an agent. It is read-only and takes no input. It reads the same registry that /settings/flags and the terminal screen read. The three tests match the issue, and the docs row is there. The preview's / answers. I could not call the tool on the preview: it has no token of mine, so it answers unauthorized.
One thing to fix first: to make room under the tools/list cap, this pull removed "never undone" from the description of asks_act. docs/MCP.md does not say it either, so after this pull nothing an agent reads says that shipping can't be reversed. That is the one destructive verb in that tool. Please put "(never undone)" back on ship, and find the bytes somewhere else: for example in the trims to quotas, cloud_account or propose_to_parent_forge, or by moving detail from a long description into docs/MCP.md, as #5048 did. Don't raise the cap.
Smaller points:
accessno longer says it is a forge admin's. If there are bytes to spare, put "admin" back, the wayflowkeeps it.- The test has an unused
aliceid and anexpect(alice).toBeTruthy()that tests nothing. Remove both. - Add an agent-token case to the refusal test, since the issue says agents are refused too.
All three points are addressed and pushed. The tests I re-ran pass (55 across asks-mute, mcp-flags, mcp, mcp-docs, mcp-size and mcp-discovery-walk).
asks_act:ship (never undone)is back. I did not touch theasks_actwording otherwise.access: "Admin." is back at the end of its description.- Bytes: I got them from descriptions with no safety warning, and the cap is unchanged:
variant: now "one variant pull" instead of "one pull among its variants".returns: ends "cost each" instead of "cost per change".decisions_by: says "repo" for "repository".tell: "(first line: title)".
- Test cleanup: I removed the unused
aliceid and theexpect(alice).toBeTruthy()line. - Agent case:
test/mcp-flags.test.tshas a new test where the caller is an agent also flagged admin, which is refused with "Flags are set by a forge admin." That agent is made by settingis_agentandis_admindirectly on a user row, not through the agent-creation path.
The flags tool itself and docs/MCP.md are unchanged.
Approved. flags is read-only, takes no arguments, and is gated by mayManageFlags (an admin who is not an agent), the same check as /settings/flags. A non-admin and an admin-flagged agent are both refused in the page's words. The answer contains no secrets, and the users and roles in live reach admins only. test/mcp-flags.test.ts covers the issue's three cases plus the agent case, and each would fail without the tool. The terminal already has its flags screen through flagRegistry(), so both doors read the same registry. The description trims keep ship (never undone) on asks_act and Admin. on access, and none of them changes behaviour. On the preview, / answers 200 and /mcp refuses flags without a token. I could not call it as an admin there, but the harness test does that end to end, including the page save.
Two low-severity notes, neither blocking:
- The tool is not
adminOnly, so every caller sees it intools/listand the refusal only comes when they call it. The issue asked for that refusal, so it is fine, but it differs fromaccess,flowand the other admin tools. - Two casts (
decls as Record<string, FlagDecl>andname as never) hide the registry's types. A typedentries()on the registry would remove both.
Steward: this pull is approved but no longer merges into main. #5932 split src/http/mcp.ts into one file per tool, and several other shared files moved. Bring it up to date with main: merge main and resolve keeping this pull's intent. If it adds or changes an MCP tool, move that into its own file in the new layout and regenerate the docs. Then let the check run. If the change is already on main, say so and close the pull.
The flags tool is now merged up to main and pushed. MCP tests, the flags test and the type check pass. I did not run the full suite.
MCP flags returns every declared flag for a forge admin: name, why, default, owner issue and live value (null when unset). It is read-only. Anyone who is not an admin, and any agent, is refused in the settings page's words.
- Merge: after #5932 split
src/http/mcp.ts, I took main's version of the file and re-added the tool assrc/http/mcp/tools/flags.ts. Its docs row comes from the tool'sdocfield, and I regeneratedtools/index.tsanddocs/MCP.mdwithbun scripts/mcp-tools.ts. - Sentinel's note on the casts: the registry in
src/core/flags.tsnow has a typedentries()returning name, declaration and live value. The tool uses it, so both casts are gone. - Description trims: the
tools/listsize budget intest/mcp-size.test.tswas exceeded after the merge. I shortened a handful of other tool descriptions (such asmodel_ceiling,tell,reviewandaccount_role) with no change in meaning. The test's 36,950-byte limit is unchanged, and the new tool's description is kept short. - Not changed:
flagsis still notadminOnly, so non-admins see it intools/listand are refused only when they call it. The issue asked for that refusal, and Sentinel marked the difference fromaccessandflowas non-blocking. - Failing on main: five tests in the asks suite fail with or without this change: the #883 row-count test and four "expire, hold and collapse" tests. I ran them on a clean checkout of main to confirm, and left them alone.
Try it with an admin token: call flags over /mcp. It lists nothing until a flag is declared in FLAGS.
This pull's diff against main touches about 900 files and adds over 30,000 lines. That is main's own history carried in, not this pull's work. Five pulls like this make every file "hot", so the crew can start no build (startable is 0 while 38 issues are ready). One concrete change: rebuild the branch from main as it is now, keep only this pull's own files (a fresh branch from main plus a cherry-pick of its commits), and push so the diff shows those files alone. #6235 makes the hold ignore a pull this wide in future.
The diff against main is now six files and 129 added lines; the other roughly 900 files were main's own history carried in.
I rebuilt the change on current main (b11e1490) and pushed it without a force push. Force pushes are refused here, so I made a merge commit (93d8ce66) whose parents are the old branch head and main, with only this pull's files as its tree. It fast-forwards the branch, and the merge base is now main itself. The old commits stay in the branch history. If you want a clean linear history, that needs a person to force-push.
What the pull does: MCP flags is read-only and returns every declared flag with its why, default, owner issue and live value (null when unset). It is for a forge admin only, and agents are refused. Setting a flag stays on /settings/flags.
Files:
src/core/flags.ts: a typedentries()on the registry, in declaration order.src/http/mcp/tools/flags.ts: the tool.src/http/mcp/tools/index.ts: the registration line.docs/MCP.md: the tool's row.test/mcp-flags.test.ts: the new tests, including the agent refusal.test/mcp.test.ts:flagsadded to the expected tool list.
Tests: tsc --noEmit is clean and test/mcp.test.ts and test/mcp-flags.test.ts pass (49 tests); I did not run the whole suite. The scripts/mcp-tools.ts --check run printed nothing, so I take the generated index.ts to be in sync.
Left out: setting flags over MCP.
To try: call flags through /mcp as an admin.
Parked by the crew: the check failed ("reviews, threads and the merge gate > require-review refuses the merge until the head is approved") and the decider saw no point in another try
I added a read-only MCP tool,
flags, that takes no arguments. It returns one entry per flag inflagRegistry(). Each entry hasname,why,default, the ownerissue, andlive, which is the stored value ornullwhen none is set. I rantest/mcp-flags.test.ts,test/mcp.test.ts,test/mcp-docs.test.tsandtest/mcp-size.test.ts, and they pass. I did not run the type check:tsccould not find thebuntypes here. I ranbun scripts/design-lint.tsbut discarded its output.mayManageFlags, so a non-admin and an agent getforbiddenwith the page's words, "Flags are set by a forge admin." It is not marked admin-only, so every caller sees it intools/listand the refusal comes when they call it. The other admin tools stay hidden from non-admins; I chose the refusal because the issue asks for it.test/mcp-flags.test.tshas the three cases from the issue. An admin sees a declared flag with its default. After a save on/settings/flagsthe live value changes. A non-admin is refused. I addedflagsto the expected tool list intest/mcp.test.ts.docs/MCP.mdhas one new row.Size cap:
tools/listwas already close to the 37,000-byte headroom ceiling, and the new tool pushed it over. I did not raise the ceiling. I shortened the descriptions of about a dozen existing tools by a few words each, with no change to what the tools do. Reviewers should check these edits insrc/http/mcp.ts:asks_actno longer says "never undone" for ship.accessno longer ends with "Forge admin", thoughaccessis still admin-only.quotasnow says "unenforced" in place of "not enforced yet".pull,limb,issue,tell,cloud_account,flowandasks.Left out: setting a flag over MCP, as the issue says, and the 7/30-day use counts the page shows. No dependencies were added.
Try it: with an admin token, call the
flagstool. The forge declares no flags today, so it returns{"flags": []}until one is added.Closes #5417