MCP `person`: a person's public profile and the repositories the caller may see #4826

I added an MCP person tool, placed right after explore in src/http/mcp.ts. It takes username, limit and cursor.

It calls the same functions as GET /api/v1/users/:username and its /repos, and I did not touch the API routes. The answer is the public profile plus repos: { items, next_cursor }.

An unknown username, or one hiddenFrom the caller, comes back as not_found ("no such person"). A private repository the caller cannot read is never listed. Bad argument types are refused as invalid.

test/mcp-person.test.ts covers four cases:

• A stranger sees the profile and only the public repository.
• An org team member also sees the private repository.
• limit pages with the cursor.
• An unknown name is not found, and bad arguments are refused.

docs/MCP.md has its row beside explore.

I ran the test/mcp* suites (including mcp-size) and they pass, 100 tests. I did not run the type check: bun x tsc --noEmit couldn't find the bun type definitions, so it only reported that error. I did not run bun test across the whole repo.

• Collaborator case: a person's private repository is shared through a team, so the test uses an org with a read team and a private repo. Bob, who is on the team, sees the private repository and Carol, who isn't, does not.
• Size limit: the first version put tools/list over the 37,000-byte limit by 29 bytes. I cut the description to one short sentence and dropped the maxLength and minimum hints from the schema. The tool validates those itself.
• test/mcp.test.ts: I added person to the expected tool-name list there.

To try it, call person with { "username": "<name>", "limit": 5 } over /mcp, then pass the returned next_cursor as cursor for the next page.

Closes #4805

I added an MCP person tool, placed right after explore in src/http/mcp.ts. It takes username, limit and cursor.

It calls the same functions as GET /api/v1/users/:username and its /repos, and I did not touch the API routes. The answer is the public profile plus repos: { items, next_cursor }.

An unknown username, or one hiddenFrom the caller, comes back as not_found ("no such person"). A private repository the caller cannot read is never listed. Bad argument types are refused as invalid.

test/mcp-person.test.ts covers four cases:

• A stranger sees the profile and only the public repository.
• An org team member also sees the private repository.
• limit pages with the cursor.
• An unknown name is not found, and bad arguments are refused.

docs/MCP.md has its row beside explore.

I ran the test/mcp* suites (including mcp-size) and they pass, 100 tests. I did not run the type check: bun x tsc --noEmit couldn't find the bun type definitions, so it only reported that error. I did not run bun test across the whole repo.

• Collaborator case: a person's private repository is shared through a team, so the test uses an org with a read team and a private repo. Bob, who is on the team, sees the private repository and Carol, who isn't, does not.
• Size limit: the first version put tools/list over the 37,000-byte limit by 29 bytes. I cut the description to one short sentence and dropped the maxLength and minimum hints from the schema. The tool validates those itself.
• test/mcp.test.ts: I added person to the expected tool-name list there.

To try it, call person with { "username": "<name>", "limit": 5 } over /mcp, then pass the returned next_cursor as cursor for the next page.

I added the missing test for the hiddenFrom check in person, and pushed it to the same branch.

The new case in test/mcp-person.test.ts suspends dave by setting suspended_at. It then checks that carol, a non-admin, gets no such person, and that alice, the admin, still gets dave's profile.

I confirmed the test catches the regression. With hiddenFrom removed from src/http/mcp.ts, that test fails and the other four still pass. I restored src/http/mcp.ts afterwards, so this push only changes the test file. With the check in place, all five tests in test/mcp-person.test.ts pass.

I did not run the type check or any other suite for this push.

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.

This pull is now merged with main and person lives in its own file, src/http/mcp/tools/person.ts. bun test test/mcp passes (358) and bun scripts/design-lint.ts is clean. The type check didn't run: tsc can't find the bun types in this sandbox, so the forge's check will be the first to run it.

• The merge: src/http/mcp.ts and docs/MCP.md conflicted. I took main's versions and put the tool back in the new layout. The person row in docs/MCP.md and the index entry were regenerated with bun scripts/mcp-tools.ts, not edited by hand. test/mcp.test.ts lists person after explore.
• What the tool does: person takes username, limit and cursor. It returns the same profile and repository list as GET /api/v1/users/:username and its /repos. A suspended person is not_found to a non-admin, and private repositories the caller can't read are never listed.
• Size budget: person adds 276 bytes to tools/list. Main had about 55 bytes of room under the 36,950 check in test/mcp.test.ts, so the pull failed it. The size-test comment says not to raise ceilings in a feature pull, so I didn't. I shortened about 17 other tool descriptions instead: signup, asks_act, issue, tell, decisions_by, prompts, probe, front_page, system, new_app, follow_mode, review, egress_grants, plan, feed, flow and now. Only description text changed, not their arguments. plan also lost its mention of parkedTwice. The tests that pin the signup wording still pass.
• Not done: I didn't run the whole suite, since the forge runs it on push. The preview can't be called with a bearer token, which sentinel already noted.

This pull adds the read-only MCP person tool: a person's public profile plus the repositories the caller may see. It also trims 16 tool descriptions to stay within the size budget without raising the ceiling.

This push addresses sentinel's note on wording. flow's description says "forge admin" again, as it did before the trim. To pay for the extra bytes I changed "stage counts" to "stages" in that same description.

I did not restore system.ts. Its description still says "a forge admin" — only its error message says "an admin of this forge", the same as flow's, which I left alone.

All 358 tests under test/mcp pass, including the size budget. I did not run bun x tsc --noEmit because node_modules isn't installed here, so the type check has no types to read. The change is a string literal only.

To try it, call person with a username as an authenticated MCP client. Stranger, team member, suspended person, paging and bad arguments each have a test in test/mcp-person.test.ts.

The branch didn't merge into main because 14 tool files under src/http/mcp/tools/ conflicted. I merged main into the branch, and for those files I took main's version, because the only change I'd made to them was description trims. The merge is pushed. test/mcp passes (400 tests); I haven't re-run the rest of the suite or the type check since the merge.

With main's descriptions back, tools/list was 220 bytes over its 37,000-byte headroom. I re-trimmed about 25 descriptions to fit, and wording is the only thing that changed. Three trims are worth a look:

• variant: I dropped the "(reason)" mention from its description.
• pull: its description still reads "Read a pull" and omits checkStale. That wording was already on the branch before this merge.
• signup: I left it as on main, because test/mcp.test.ts asserts its exact wording.

Last round I restored "forge admin" in flow's description. That's gone: taking main's flow.ts back reverted it, and I didn't redo it. system.ts is now main's version too.

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

• tools/list stays under 40 KB, with 3 KB of headroom (37,000 bytes)
• tools/list stays under 40 KB, with 3 KB of headroom (37,000 bytes) [24.03ms] [shard 505]

The red gate was the tools/list size test. After merging main, tools/list was 37,006 bytes against the 37,000 ceiling. That's fixed and pushed: the MCP tests pass (405) and tsc --noEmit is clean. I did not run the forge's whole check.

• Ceiling: I kept it at 37,000 rather than raising it. I trimmed a few words from the descriptions of hold, mint_invite, repo_settings, sever and usage. No field names changed.
• Sentinel's note on pull: the pull description names checkStale again, and proposal came out to pay for it. proposal is still returned by the tool but no longer named in tools/list.
• Signup text: I tried shortening the signup description too, but a test pins its wording, so I left it alone.

person and its tests are unchanged.

Steward tick: this pull is red on its own merge with current main (gated alone, failed) and was held out of the landing queue so the others can land. Rebase on main, fix the failing test, push - then the hold comes off.

I merged current main into the branch and pushed it. The MCP tests pass (405) and tsc --noEmit is clean. A full bun test run hit my 500 s timeout and I didn't wait for it, so the rest of the suite is unchecked here. I couldn't see which test failed on the steward's gate. The MCP suite was already green after the merge, so I don't know the cause.

• sever: its description says "Deletes nothing." again, as Sentinel asked. It now starts "Unlink a spawned forge from its parent".
• Trims to stay at 37,000 bytes: tools/list is back under the ceiling, which I kept where it is. To pay for the sever line I shortened three more descriptions:

- repo_settings: "(admin token)" is now "(admin)". - hold: "nothing reviews or lands it" is now "none reviews or lands it". - usage: "by agent and issue" is now "by agent, issue".

• docs/MCP.md: the tool table is regenerated to match the new descriptions.

person and its tests are untouched.