forgejo-mcp/openspec/changes/mcp-resource-templates/proposal.md

Why

forgejo-mcp is tool-only today. Core Forgejo entities (owner, repo, commit, issue, pr, comment, status) are noun-like, sha- or index-addressable, and often stable — natural MCP resource candidates. Exposing them as URI-addressable resources unlocks auto-resolution from LLM context (e.g. a sha mentioned in a PR diff is fetched without an explicit tool call), content-addressable caching for immutable entities (commits, statuses pinned to a sha), and composable references between entities. Doing this one entity at a time would leave the server in a mixed tool/resource state with inconsistent URI conventions; this change designs all seven entities at once and lets tasks land incrementally.

What Changes

• Add resource-template support to operation/operation.go server construction: register server.WithResourceCapabilities(...) and define resource templates for each entity (no implementation yet — design only).
• Introduce a forgejo:// URI scheme with one template per entity:
  • forgejo://owner/{owner} — user or organization
  • forgejo://repo/{owner}/{repo} — repository metadata
  • forgejo://repo/{owner}/{repo}/commit/{sha} — commit metadata
  • forgejo://repo/{owner}/{repo}/issue/{index} — issue
  • forgejo://repo/{owner}/{repo}/pr/{index} — pull request
  • forgejo://repo/{owner}/{repo}/{kind}/{index}/comment/{id} — comment (kind ∈ issue, pr)
  • forgejo://repo/{owner}/{repo}/commit/{sha}/status — combined CI status for a commit
• Establish a per-domain resource/ subpackage pattern under operation/{domain}/ paralleling the existing tool pattern, with a RegisterResources(s *server.MCPServer) entry point.
• Define coexistence rules with existing tools: resources are read-only entity fetchers; mutating actions (create issue, merge PR, post comment) stay tools. Existing read-only list tools (list_repo_issues, list_pull_request_files, …) stay — they are bounded queries, not single-entity fetches.
• Apply output-bounding contract from docs/design/output-bounding.md to resource responses: any embedded list (e.g. comment threads on an issue resource, statuses on a commit resource) must be capped with an explicit truncation marker and link to a list tool for enumeration.
• Document client-compatibility expectations: targets clients that implement MCP resources/templates/list and resources/read (Claude Code, Claude Desktop, Codex, current Cursor). Clients without template support fall back to existing tools — no functionality removed.
• Subscription semantics: explicitly OUT of scope for v1. No resources/subscribe handler. Resources are read-on-demand only.
• Auth & errors: resources reuse the existing singleton pkg/forgejo client; private-entity reads return MCP error with the same 403 / 404 mapping the tools use today.

Capabilities

New Capabilities

• mcp-resources-core: Resource-template registration framework — URI scheme, capability declaration on the MCP server, per-domain RegisterResources entry point, shared URI parser, error mapping, output-bounding rules for embedded lists, and the coexistence contract between resources and tools.
• mcp-resource-owner: forgejo://owner/{owner} template — resolves a user or organization, returns identity metadata.
• mcp-resource-repo: forgejo://repo/{owner}/{repo} template — repository metadata (name, default branch, visibility, description, counts).
• mcp-resource-commit: forgejo://repo/{owner}/{repo}/commit/{sha} template — commit metadata (author, committer, message, parents, tree sha); immutable, marked cacheable.
• mcp-resource-issue: forgejo://repo/{owner}/{repo}/issue/{index} template — issue body, labels, assignees, state, milestone; recent comments embedded with bound + truncation marker.
• mcp-resource-pr: forgejo://repo/{owner}/{repo}/pr/{index} template — PR metadata, head/base refs, mergeability; recent comments and review summaries embedded with bound + truncation marker.
• mcp-resource-comment: forgejo://repo/{owner}/{repo}/{kind}/{index}/comment/{id} template — single comment body and metadata; kind discriminates issue vs PR comments.
• mcp-resource-status: forgejo://repo/{owner}/{repo}/commit/{sha}/status template — combined CI status (state + per-context statuses) for a commit sha; pinned to sha, cacheable.

Modified Capabilities

Impact

• Affected code: operation/operation.go (server construction, capability flag, new RegisterResources* calls); seven new operation/{domain}/resources.go files (one per entity); a new shared operation/resource/ package for URI parsing, template registration helpers, and embedded-list bounding. No changes to existing tool files.
• No new external dependencies. Uses mcp-go resource APIs already pulled in transitively via server.MCPServer. Uses the singleton pkg/forgejo client unchanged.
• No breaking changes. All existing tools remain. Clients that don't support resource templates see exactly today's surface.
• Documentation: README gains a "Resources" section paralleling the tool table; docs/design/output-bounding.md is referenced (not amended) for the embedded-list rule.
• Rollout: per-entity tasks let mcp-resources-core + mcp-resource-commit land first as a thin slice (highest immediate value for CI/status workflows), with the remaining six entities following independently. Each entity entry-point is gated behind its own RegisterResources* call so partial rollout is safe.
• Out of scope for this change: implementation (specs + design only), wiki/projects resources (blocked upstream per docs/plans/), webhook/event resources, resources/subscribe, write-through resources.