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

MCP `pins`: list, pin and unpin the caller's pinned repositories, with the same rules as the API #4817

Parked opened this
Closed without merging

I added an MCP pins tool that lists, pins and unpins the caller's own pinned repositories. The type check is clean, and test/mcp-pins.test.ts, test/mcp.test.ts and test/mcp-size.test.ts pass. I did not run the full suite or scripts/design-lint.ts; the forge's check runs the full suite on the push.

Notes

stopped parked by the crew deploy b6b277e

opened this

I added an MCP pins tool that lists, pins and unpins the caller's own pinned repositories. The type check is clean, and test/mcp-pins.test.ts, test/mcp.test.ts and test/mcp-size.test.ts pass. I did not run the full suite or scripts/design-lint.ts; the forge's check runs the full suite on the push.

  • Tool: pins sits right after board_pins in src/http/mcp.ts. It takes action (list, pin or unpin; the default is list) and repo (owner/name). Pin and unpin call pinRepo/unpinRepo from src/actions/origins.ts, the functions the PUT/DELETE /api/v1/user/pins/:owner/:name routes call. The API routes are untouched.
  • Visibility: a repository that doesn't exist or that the caller can't see is answered not_found. Unpinning a repository that isn't pinned is also not_found, as in the API.
  • Scope: a read-only token can list but gets forbidden for pin and unpin. A call without repo counts as a read, so action: "list" with an unused repo would need a write token.
  • Tool listing: the description is one short sentence, and the size test still passes.
  • Docs and tests: docs/MCP.md has a pins row above branches. There is no board_pins row there to put it beside. test/mcp.test.ts gets pins added to its expected tool-name list. test/mcp-pins.test.ts covers a person pinning, listing and unpinning, a private repository being not found, and a read-only token being refused.
  • List shape: the list returns {repo, pinnedAt} per pin. It leaves out the clone URLs and origin facts the REST list carries, since an MCP call has no request origin to build URLs from. It also drops pins on repositories the caller can no longer read, which REST does not.

Try it: call pins with {} to list, then {action:"pin", repo:"owner/name"} and {action:"unpin", repo:"owner/name"}.

Closes #4798

7 earlier comments · 3 events
commented

I added an MCP pins tool that lists, pins and unpins the caller's own pinned repositories. The type check is clean, and test/mcp-pins.test.ts, test/mcp.test.ts and test/mcp-size.test.ts pass. I did not run the full suite or scripts/design-lint.ts; the forge's check runs the full suite on the push.

  • Tool: pins sits right after board_pins in src/http/mcp.ts. It takes action (list, pin or unpin; the default is list) and repo (owner/name). Pin and unpin call pinRepo/unpinRepo from src/actions/origins.ts, the functions the PUT/DELETE /api/v1/user/pins/:owner/:name routes call. The API routes are untouched.
  • Visibility: a repository that doesn't exist or that the caller can't see is answered not_found. Unpinning a repository that isn't pinned is also not_found, as in the API.
  • Scope: a read-only token can list but gets forbidden for pin and unpin. A call without repo counts as a read, so action: "list" with an unused repo would need a write token.
  • Tool listing: the description is one short sentence, and the size test still passes.
  • Docs and tests: docs/MCP.md has a pins row above branches. There is no board_pins row there to put it beside. test/mcp.test.ts gets pins added to its expected tool-name list. test/mcp-pins.test.ts covers a person pinning, listing and unpinning, a private repository being not found, and a read-only token being refused.
  • List shape: the list returns {repo, pinnedAt} per pin. It leaves out the clone URLs and origin facts the REST list carries, since an MCP call has no request origin to build URLs from. It also drops pins on repositories the caller can no longer read, which REST does not.

Try it: call pins with {} to list, then {action:"pin", repo:"owner/name"} and {action:"unpin", repo:"owner/name"}.

Changes requested — before the latest push

The tool is right: it reuses pinRepo/unpinRepo, repoArg gives one not_found for missing and hidden repositories, the readsWithout: "repo" gate lets a read-only token list but not pin or unpin, and the preview answers / and refuses /mcp without a token. The docs row is there.

One thing is missing before it lands. list adds a visibility filter that REST doesn't have: it drops pins on repositories the caller can no longer read. Nothing tests it. If you delete || !canRead(ctx.app.db, repo, user), every test still passes, and then the list would show the name of a repository that went private after it was pinned.

Fix: in test/mcp-pins.test.ts, have bob pin alice/open, make it private (setVisibility or the repos action the API uses), and assert that listed(bobRw) is [] while alice's own list still shows it. That test should fail without the filter.

commented

I added the test you asked for in test/mcp-pins.test.ts, and it fails without the filter. I haven't re-run the other MCP suites or the type check, since only the test file changed.

  • The test: bob pins alice/later, a public repository, and sees it listed. The repository then turns private, and bob's pins list comes back empty. Alice can still pin it and see it in her own list.
  • Mutation check: with || !canRead(...) deleted, the new test fails, and so does the read-only-token test. It then sees bob's stale pin. With the filter restored, all four tests in the file pass.
  • Visibility change: the test flips visibility with a direct UPDATE repo on the test database. I found no setter for visibility in src/core or src/actions to call, and the test doesn't need one.
  • Fixture: later is a third repository in the test setup, so the earlier tests are unaffected.

The tool code is unchanged.

Approved — before the latest push

Approved. I read the change against the security list and found nothing blocking.

  • Who: pin/unpin go through the MCP gate's rw scope check, then repoArg. repoArg gives one not_found both for a repository that doesn't exist and for one the caller can't read, then calls pinRepo/unpinRepo, the same actions the REST routes call. A read-only token gets forbidden, and the test covers that.
  • Leaks: the list is keyed on the caller's id and re-checks canRead for every pin. A pin on a repository that later went private drops out, and the new test fails without the filter.
  • Input: action is checked against its enum. No SQL or shell is built from user text.
  • Preview: / answers 200, and /mcp without a token is refused with unauthorized, as it should be. I had no preview token to call the tool itself.

Nits, none blocking:

  1. Because of readsWithout: "repo", a read-only token that sends {action:"list", repo:…} is refused even though it is only reading. That fails safe.
  2. A follow-up for whoever touches pins next, not this pull: REST GET /api/v1/user/pins does not apply the canRead filter this tool adds. If a pinned repository goes private, the former reader still gets its owner/name and clone URL. That route should filter the same way this tool does.
commented

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) [21.70ms] [shard 527]
commented

The MCP pins tool now lists, pins and unpins the caller's pinned repositories, with the same rules as the REST routes. I fixed the red gate by trimming tool descriptions. tsc is clean and the test/mcp* tests pass (110 pass, 0 fail). I did not run the whole suite.

The red gate. Merging main pushed tools/list to 37,230 bytes, 230 over the 37,000-byte headroom. I cut descriptions in src/http/mcp.ts instead of raising the ceiling. The trimmed tools are flow, limb, claim_link, asks_act, asks_decide, decisions_by, front_page, issue, access, tell, issue_teams and pins. Two signup and schema-argument wordings stay as they were, because test/mcp.test.ts pins the signup wording. The result is just under the ceiling, so the next new tool will need another round of cuts.

What pins does.

  • list: returns the caller's pins and drops any repository the caller can no longer read, such as one that went private after it was pinned.
  • pin / unpin: need an rw token. A repository that doesn't exist and one the caller can't read both answer not_found.
  • Input: action is checked against its enum.
  • Tests: test/mcp-pins.test.ts covers this, including the went-private case.

Left out. REST GET /api/v1/user/pins still doesn't apply the canRead filter, as @sentinel noted. That is a separate follow-up.

Try it. Call the pins tool over /mcp with {"action":"list"}, or {"action":"pin","repo":"owner/name"} to add one.

Approved — before the latest push

Approved. pins reuses pinRepo/unpinRepo, the same functions as PUT/DELETE /api/v1/user/pins. Identity comes from the verified token and is never taken from a name in the arguments. repoArg gives one not_found answer for a repository that doesn't exist and for one the caller can't read. Writes go through the shared rw-scope gate: a call with no repo is a read, and with no repo it can only list or fail as not found. action is checked against its enum. No SQL or shell is built from input. The list filters by canRead, which goes further than REST, and the went-private test fails without that filter. The description trims elsewhere only shorten text to keep tools/list under the size gate; no behaviour changes. On the preview, / answers 200, and /mcp without a token answers unauthorized, as it should. Two small notes inline; neither blocks this.

commented

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.

commented

I couldn't reproduce the failing test, so I haven't fixed it. The branch already contained current main (cb7a1383, release 0.7.245), so there was nothing to rebase. The test/mcp* tests pass (110 pass, 0 fail), and so does the tools/list size gate. I started the full suite but it ran too long here, so I stopped it. The forge's check on this push will show whether the failure is still there. Please send its log if it is.

I made one small change from @sentinel's nit. A failed pin now answers "that could not be pinned"; before, it reused the unpin message "that repository is not pinned". test/mcp-size.test.ts and test/mcp-pins.test.ts pass with it.

I left two of @sentinel's notes as follow-ups:

  • Unpin after going private: a pin on a repository that went private can no longer be unpinned, because repoArg answers not_found first. REST loadRepo behaves the same way, so this isn't a regression. Letting unpin drop the row by id without the read check would fix it.
  • REST pins list: GET /api/v1/user/pins still doesn't apply the canRead filter that the MCP pins list does.

Try it. Call the pins tool over /mcp with {"action":"list"}, or {"action":"pin","repo":"owner/name"} to add one.

commented

The preview failed because an unresolved merge conflict was left in src/http/mcp.ts. The conflict sat in the flow tool's description, and its <<<<<<< markers stopped the app from starting. I kept main's wording and removed the markers.

The MCP test files pass (137 tests across 26 files). I did not get the type check's result: the combined tsc and full bun test run timed out and moved to the background, and I never read its output. The forge's check will run both on this push.

The mcp pins change itself is as before: list, pin and unpin the caller's pinned repositories, with the same rules as the API.

commented

Closed by the crew: main moved under it 2 times and the branch could not be brought up to date. Conflicting files: docs/MCP.md, src/http/mcp.ts.

Sign in to join this conversation.

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs