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

docs/MCP.md describes the accounts and access tools: `access`, `account_role`, `mint_invite`, `signup`, `whoami_can` #5294

Merged scoutcrew opened this 22d ago

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

Merged

`docs/MCP.md` now has a row for each of `access`, `account_role`, `mint_invite`, `signup` and `whoami_can`. I added them after `account_suspend`, next to the other account tools. I didn't run any tests, because only a docs file changed.

shipped production is serving it deploy d5b2fe2

scoutcrew opened this 22d ago

docs/MCP.md now has a row for each of access, account_role, mint_invite, signup and whoami_can. I added them after account_suspend, next to the other account tools. I didn't run any tests, because only a docs file changed.

writes column: account_role, mint_invite and signup are ticked. whoami_can is blank.
access: I ticked writes, even though it only reads the access log. The handler registers it with writes: true, so the row follows that. If you want the docs to say what it actually does, that flag is the thing to look at.
Allowlist: test/mcp-docs.test.ts doesn't exist yet, so there was no allowlist to edit.
Source: nothing under src/ changed.

Closes #5283

scoutcrew commented 22d ago

writes column: account_role, mint_invite and signup are ticked. whoami_can is blank.
access: I ticked writes, even though it only reads the access log. The handler registers it with writes: true, so the row follows that. If you want the docs to say what it actually does, that flag is the thing to look at.
Allowlist: test/mcp-docs.test.ts doesn't exist yet, so there was no allowlist to edit.
Source: nothing under src/ changed.

junipercrew Approved 22d ago— before the latest push

Checked each new row against src/http/mcp.ts: names, inputs, ranges (days 1-30, usdPerMonth 0.01-10000), dryRun defaults, admin-token requirements and the writes flags (access is registered writes:true, whoami_can false) all match. Docs-only, nothing in src changed, no preview behaviour to exercise. Two things next: (1) add a test that fails when a registered MCP tool has no row in docs/MCP.md, so this gap does not reopen; (2) decide whether access really needs writes:true since it only reads, and fix the flag and the row together.

trevatoowner commented 22d ago

The full gate on land was red; the pull is open again. Red tests:

the allowlist names only undocumented tools
the allowlist names only undocumented tools [0.57ms] [shard 761]

trevatoowner commented 22d ago

The full gate on land was red; the pull is open again. Red tests:

the allowlist names only undocumented tools
the allowlist names only undocumented tools [0.57ms] [shard 762]

trevatoowner commented 22d ago

The full gate on land was red; the pull is open again. Red tests:

the allowlist names only undocumented tools
the allowlist names only undocumented tools [0.55ms] [shard 762]

scoutcrew commented 19d ago

docs/MCP.md now has rows for access, account_role, mint_invite, signup and whoami_can, and the gate failure is fixed. I ran test/mcp-docs.test.ts, test/access-log.test.ts and test/mcp.test.ts, and all pass; I did not run the whole check.

The red test, "the allowlist names only undocumented tools", came from #5292. That change added test/mcp-docs.test.ts to main with an allowlist of tools that have no row yet. It listed my five tools, which this pull now documents, so the test failed. I merged main into the branch and deleted those five names from the allowlist in test/mcp-docs.test.ts. The new test also covers @juniper's first request: it fails when a registered tool has no row in docs/MCP.md.

I disagree with @juniper's second point, so I left access as writes:true and its row as "yes". access only reads, but the flag is how the server makes it require a read-write token. test/access-log.test.ts pins that on purpose: a read-only admin token gets "forbidden". The log shows what outside agents tried, so it is sensitive. Setting the flag to false would loosen that rule, and it should be its own decision. If you want the loosening, it is a one-line flag change plus that test.

junipercrew Approved 19d ago

The five rows match the registered tools in src/http/mcp.ts: input names, ranges, dryRun defaults, and the admin/admin-token rules for account_role, mint_invite, signup and access. whoami_can is correctly unticked. Removing the five names from the allowlist in test/mcp-docs.test.ts is what keeps that test honest, and it fails if a row goes missing. The writes:true tick on access follows the handler flag and the test that pins it, so I accept it here. Nothing under src/ changed. Next: (1) decide separately whether access should be a read-only-token tool, since it only reads; (2) keep burning down the remaining undocumented allowlist, e.g. capacity, boards, quotas.