feat(mcp): serve pull requests, diffs, files and commits as resources, with prompts and completions

[vriesdemichael]

Implements #685: bb's MCP server serves Bitbucket content as resources, with prompts and completions, so the person can hand a pull request, a diff or a file to the model from a picker.

What changes

• Resource templates under bitbucket://projects/{project}/repos/{repo}/:

  • a pull request, its diff and its open threads;
  • a file at a ref (files/{+path}{?at});
  • a commit.

  bb reads them with its own credentials, so the client never contacts Bitbucket. Each answers with what its tool answers, through the same function, bounded as ADR-094 asks: the diff is capped at 128 KiB and the threads at 100.

• Served with their tools. A template is served while the tool it answers like is exposed, a prompt while every tool it embeds is, and the list while list_pull_requests and get_pull_request are. --tools and --exclude therefore decide them too, and capabilities follow what is served.

• resources/list holds your open pull requests and those waiting on your review, 25 of each. The dashboard narrows by project and repository inside its walk, so the cap counts what is in scope.

• completion/complete completes project, repository, pull request, path and ref, using the listing the shell uses, which moves to internal/services/listing. Each server runs at most two at a time, with at most 100 values an answer.

• Prompts: review_pull_request (details, diff and open threads embedded) and explain_pull_request (details and diff).

• Governance.

  • --project/--repo bind reads, the list, prompts and completions.
  • Under a scope, a project or repository completion is answered without asking Bitbucket.
  • Reads, the list and prompts are audited as mcp_resource_read, mcp_resource_list and mcp_prompt_get. Completions are not audited.

• Links. get_pull_request, get_pr_diff, get_file_content and get_commit add a resource_link beside their content, for clients on protocol revision 2025-06-18 or later.

• Video. get_file_content addresses a returned video by its bitbucket:// URI instead of its web page, which a client could fetch without the credentials.

• 2026-07-28 rules. A missing resource is -32602, reads and the list are cacheScope: private, and every capability is declared bare.

• URIs. bb builds and parses its URIs itself, escaped as UTF-8. The URI template library go-sdk routes with encodes non-ASCII as code points and refuses U+FFFD.

Review before pushing

A second pass (mine plus an independent review) found and fixed:

• A crash: U+FFFD in a prompt argument, or in a path or ref that a tool call succeeded with, made the URI library fail, and bb panicked.
• Wrong links for non-ASCII: "é" encoded as %E9, not UTF-8.
• Unfiltered resources: --tools/--exclude did not govern resources, so the hardening guide's allowlist still served files.
• Links to old clients: links went to revisions without resource_link, and list_pr_comments linked a resource other than its result.
• Missing pull requests: the list under --repo could leave out pull requests past the project-wide cap.
• Unscoped listing: scoped completions listed the whole instance before discarding the answer.
• A flaky subtest: the live project completion.

Tests

• Unit (no mocked Bitbucket):

  • template guards;
  • URI round trips with non-ASCII, ?, # and U+FFFD;
  • refused shapes;
  • -32602 for what does not exist;
  • scope on reads, prompts, the list and completions, including a middleware test that the pinned context reaches the listing;
  • audit events;
  • the tool filters;
  • the protocol gate for links;
  • the answer bounds.

• Guards broken first: every guard above failed when broken (17 mutations).

• Live: TestLiveMCPResourcesReadWhatTheToolsRead, 13 subtests:

  • each template read;
  • a refusal for what doesn't exist, and for a pull request in a sibling repository outside --repo;
  • the list, which leaves that pull request out;
  • completions;
  • the prompt;
  • audit events;
  • links.

  The file-content live tests check the link on every read. All 19 live MCP tests pass locally, and task quality:verify passes.

Records

ADR-099 is new. It amends ADR-062 and ADR-094, and records the alternatives other MCP servers take for resources in tool results. The PR also updates ADR-067's guard list, AGENTS.md, the generated MCP reference, the AI page, the hardening guide, the threat model, and the v5.0.0 notes (item 6, with an audit sample).

Refs #685

🤖 Generated with Claude Code

[vriesdemichael]

May auto merge after changing th preamble as in the comment.

[vriesdemichael]

This reads too technical, make it clear what changes for users, give an example. Explain why it is useful