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

Context

forgejo-mcp exposes Forgejo entities exclusively through MCP tools today. operation/operation.go constructs the server with server.WithLogging() only — no server.WithResourceCapabilities(...) — and every RegisterXTool function calls s.AddTool(...). The fourteen registered tool domains in operation/ cover the same entities this change wants to model as resources (issue, pr, repo, comment, …) plus mutating actions.

Two upstream facts shape the design:

1. mcp-go v0.44.0 is in go.mod. It provides mcp.NewResourceTemplate(uriTemplate, name, opts...) (RFC 6570 templates), server.AddResourceTemplate(template, handler), and server.WithResourceCapabilities(subscribe, listChanged bool). Handlers return []mcp.ResourceContents (text or blob variants), so each resource fetch can return one or more content blocks.
2. Output bounding is a hard rule (docs/design/output-bounding.md). Any output proportional to repository state must expose a caller-controlled bound and a way to fetch the remainder. Resource handlers must respect this even though MCP resources/read has no native limit/page parameter — bounding has to happen inside the embedded payload.

Stakeholders: MCP client authors (Claude Code/Desktop, Codex, Cursor) consuming the server; this project's tool surface (must not regress); the Forgejo API rate limiter (resource reads become an additional traffic source).

Goals / Non-Goals

Goals:

• A single coherent URI scheme (forgejo://…) covering all seven entities so client UX is uniform.
• Per-domain RegisterResources(s *server.MCPServer) entry points that mirror the existing RegisterXTool pattern, keeping the codebase navigable.
• Resources coexist with tools: clients without resource-template support keep working unchanged.
• Embedded lists inside resources (e.g. comments on an issue) follow the existing output-bounding contract.
• Cacheability hints set correctly: commit + commit-status are immutable per-sha and surfaced as such; issue/pr/comment are mutable and not flagged cacheable.

Non-Goals:

• Implementation. This change ships proposal + design + specs + tasks only; code lands under a follow-up change.
• Mutating resources. No write-through. Mutations stay on tools.
• Subscriptions. server.WithResourceCapabilities(subscribe=false, listChanged=false) for v1. No resources/subscribe handler.
• Wiki / projects resources. Blocked upstream (see docs/plans/wiki-support.md, docs/plans/projects-support.md).
• Webhook / event resources. Out of scope.
• Replacing existing read tools. get_issue_by_index, get_pull_request_by_index, etc. remain. Resources duplicate the read surface for clients that prefer URI addressing; the duplication is intentional during the migration window.

Decisions

D1: URI scheme — forgejo:// (custom) over https://…/api/v1/…

forgejo://repo/{owner}/{repo}/commit/{sha} rather than the upstream REST URL.

Rationale: clients should not have to know which Forgejo instance the server is talking to (Codeberg vs self-hosted). The scheme also gives a clean discriminator between "this is an MCP resource URI" and "this is a web link the agent should open" — important because Forgejo https:// URLs appear constantly in PR bodies and would otherwise collide with the resource namespace.

Alternatives considered:

• https://<instance>/<owner>/<repo>/commit/<sha>: tempting because users paste these. Rejected because (a) it leaks instance hostname into URIs (multi-instance deployments break), (b) creates ambiguity with link-fetching behavior, (c) requires URI parsers to special-case which https:// URLs are MCP resources.
• forgejo+resource://: more explicit but ugly and unnecessary; the scheme already identifies the server.

D2: Path shape — forgejo://repo/{owner}/{repo}/<entity>/<key> (entity nested under repo)

All repo-scoped entities sit under repo/{owner}/{repo}/. Owner is a top-level peer: forgejo://owner/{name}.

Rationale: every entity except owner is repo-scoped in Forgejo; the path mirrors the API. Makes URIs predictable and templates easy to write as RFC 6570.

Alternative considered: flatter forgejo://issue/{owner}/{repo}/{index}. Rejected because it splits the natural "this lives in a repo" parent across siblings; harder to scan.

D3: Comment URIs discriminate on parent kind

forgejo://repo/{owner}/{repo}/{kind}/{index}/comment/{id} where {kind} ∈ issue | pr.

Rationale: Forgejo's API uses one comment table internally but the parent context matters for the agent (permissions, rendering, references). Embedding kind makes the URI self-describing — no need to fetch the parent to know whether a comment lives on an issue or PR.

Alternative considered: forgejo://repo/{owner}/{repo}/comment/{id}. Rejected because IDs collide across kinds in unhelpful ways and the agent loses context.

D4: Combined status URI — …/commit/{sha}/status (singular)

forgejo://repo/{owner}/{repo}/commit/{sha}/status returns the combined status (aggregate state + per-context entries). The per-context list view stays a tool (get_commit_statuses) to keep the resource a single addressable thing.

Rationale: aggregate is what callers actually want when they ask "is this sha green?". The per-context list is bounded data that benefits from page/limit parameters tools support natively but resources don't.

D5: Resource capability declaration — WithResourceCapabilities(false, false)

Subscribe = false, listChanged = false.

Rationale: v1 is read-on-demand only. listChanged would force the server to track template changes at runtime; since templates are static at startup, false is correct. Subscribe is explicitly punted — see Non-Goals.

D6: Per-domain RegisterResources(s) entry point

Each domain under operation/{domain}/ that owns one or more resources adds a RegisterResources(s *server.MCPServer) function alongside its existing RegisterTool. operation/operation.go gains a parallel list of RegisterXResources(s) calls.

Rationale: minimises diff against current layout. A reader who knows where the issue tools live finds the issue resources in the same package. No new top-level directory.

Alternative considered: a single operation/resources/ package with all handlers. Rejected because it collects unrelated entity code under one roof, defeating the per-domain locality the rest of the codebase relies on.

D7: Shared URI parser in operation/resource/

A new package (note singular) holding: RFC 6570 template registration helpers, URI parsing into typed structs (e.g. parseCommitURI(req.Params.URI) (owner, repo, sha string, err error)), and embedded-list bounding helpers. Each domain handler depends on this package, not the other way round.

Rationale: avoids duplicating URI parsing across seven domains. Keeps the per-domain handlers tiny — they go straight from typed params to a pkg/forgejo SDK call.

D8: Embedded-list bounding — sentinel + index tool reference

When a resource embeds a variable-size list (issue comments on the issue resource, statuses on a commit-status resource), the embedded payload is capped at N items (default 30, exposed as a server-side constant; revisit if telemetry shows truncation hitting frequently) and ends with a sentinel block:

[truncated: N of M items shown. Use list_<entity> tool with page=2 to fetch more.]

This satisfies docs/design/output-bounding.md sub-rules 1 (no silent truncation) and 3 (always resumable) without inventing a new query parameter on resources/read. The sentinel names the existing list tool, completing the contract.

Alternative considered: parameterise via URI query (?limit=50). Rejected because RFC 6570 template matching makes optional query params painful and most MCP clients don't surface them in URIs the LLM constructs.

D9: MIME types — application/json for entity bodies, text/markdown for rendered text fields

Each resource handler returns one or more mcp.ResourceContents. Primary content is the entity as JSON (application/json). Long markdown fields (issue body, PR description, commit message body) MAY additionally be returned as a sibling text/markdown content block, letting clients pick the form they want.

Rationale: JSON is the lingua franca for structured agent reasoning. Markdown sidecars cost little and dramatically improve LLM comprehension of formatted bodies.

D10: Caching hints — annotations on immutable resources

mcp.WithTemplateAnnotations on mcp-resource-commit and mcp-resource-status carries audience: [Role.Agent] and priority: 1.0 plus a description noting immutability. mcp-go does not currently surface an explicit cache header in the resource result, so the signal lives in the human-readable description until upstream adds one. We do NOT roll our own cache headers.

Risk noted under Risks.

D11: Auth & errors — reuse pkg/forgejo singleton + map 403/404 to MCP errors

Resource handlers go through the same client used by tools. On 403 return MCP error code -32002 (custom — match what existing tools return for access denial); on 404 return code -32003. Both with descriptive messages.

Rationale: identical semantics to today's tool errors. Clients that already handle tool-error patterns get the same UX for resources.

D12: Client compatibility — design for resources/templates/list consumers; gracefully degrade for tool-only clients

Targets clients that implement MCP resources/templates/list and resources/read (Claude Code, Claude Desktop, Codex, current Cursor). Tool-only clients keep working: every entity remains reachable via existing tools, so absence of resource support costs nothing.

Compatibility matrix to publish in README:

Client	resources/templates/list	resources/read	Notes
Claude Code	✅	✅	Primary target.
Claude Desktop	✅	✅	URL-pasted forgejo:// URIs auto-resolve.
Codex	✅	✅	Same as Claude Code.
Cursor (current)	✅	✅	Verify in implementation.
Older / minimal	⚠️ Tools only	⚠️ Tools only	No regression — tools unchanged.

D13: Rollout order — mcp-resources-core + mcp-resource-commit as the thin slice

Implementation slices land in this order, each as an independent PR:

1. mcp-resources-core (framework + URI parser + capability registration)
2. mcp-resource-commit (highest value — replaces curl-for-statuses workflows)
3. mcp-resource-status
4. mcp-resource-repo + mcp-resource-owner
5. mcp-resource-issue + mcp-resource-comment
6. mcp-resource-pr

Rationale: slice 1+2 delivers real value (commit/status fetching by sha) on its own. Each subsequent slice is independently shippable behind its own RegisterXResources call.

Risks / Trade-offs

• [Inconsistent client behavior on resource templates] → Pin compatibility matrix in README; verify each target client during implementation slice 1; keep tools as the fallback contract so non-supporting clients never lose functionality.

• [Caching not enforceable from server side in mcp-go v0.44.0] → Annotate immutable resources via description; revisit when upstream exposes explicit cache hints. Document the gap in README so client implementers don't assume server-side caching.

• [Duplicate read surface (tool + resource) confuses agents and inflates LLM context] → Specs explicitly call out coexistence; README publishes a single recommendation table ("prefer resource when you have a sha/index in hand; prefer tool when listing or searching"). If telemetry shows agents picking the wrong one, revisit by deprecating overlap rather than removing it.

• [Embedded-list truncation pointing at a wrong list tool] → Sentinel format is centralised in operation/resource/; each entity test asserts the sentinel names a tool that actually exists. Catches drift at compile + test time.

• [Forgejo API rate-limit pressure from resource reads] → Embedded lists are bounded (D8); resource handlers do not pre-fetch related entities; commit + status resources are inherently cacheable so heavy callers can dedupe by sha at the client layer.

• [URI-scheme collision with future Forgejo features] → forgejo:// is owned by this server's contract. Document the namespace in README; new entities must extend it explicitly via a new change. No catch-all path.

• [pull_request_target-style security concerns from agents auto-resolving URIs] → Resources are read-only and route through the same auth as tools. No new attack surface beyond existing tool reads. Documented in README security section.

Migration Plan

Strictly additive. No rollback strategy needed for existing tools.

Per-slice rollout (D13). Each slice ships with:

1. New RegisterXResources(s) registration in operation/operation.go.
2. Per-entity handler + tests.
3. README update appending to the resource table.

Rollback for any slice: revert the registration call in operation/operation.go. Resources disappear from resources/templates/list; tools remain.

Open Questions

• Default embedded-list cap (D8) — 30 the right number? Pulled from existing list-tool defaults. Should validate against typical issue/PR comment thread depth on Codeberg before locking in. Possibly raise per-entity (e.g. PRs have more review comments than issues).
• Should forgejo://owner/{name} distinguish users vs orgs in the URI? Current proposal does not. If clients want to know without fetching, we'd add forgejo://user/{name} and forgejo://org/{name} instead. Defer until a real use case surfaces.
• Markdown sidecar (D9) — return always, or only when the field is non-trivial (> N chars)? Default to always for simplicity; revisit if context bloat becomes a problem.
• Compatibility matrix verification (D12) — needs hands-on testing against each target client in implementation slice 1. Spec acceptance for mcp-resources-core should include a test plan covering this.