forgejo-mcp/openspec/changes/mcp-resource-templates/specs/mcp-resource-owner/spec.md at bot/downloads-20260613-061752

Christoph Görn c8c2c0afd5

docs: 📝 openspec proposal for MCP resource templates

Add full OpenSpec change `mcp-resource-templates` covering the design
for exposing core Forgejo entities as URI-addressable MCP resources:
owner, repo, commit, issue, pr, comment, and commit-status.

Artifacts:
- proposal.md: why + capability list for all 7 entities
- design.md: 13 decisions (URI scheme, coexist-vs-replace, bounding,
  caching, auth, rollout order, client compat matrix)
- specs/: 8 spec files with ADDED Requirements + Scenario blocks
- tasks.md: 7 slices (core framework → entity-by-entity → docs)

Driven by forgejo-mcp-1l5. Implementation via /opsx:apply.

2026-05-25 10:04:22 +02:00

1.7 KiB

Raw Permalink Blame History

ADDED Requirements

Requirement: Owner resource template

The server SHALL register a resource template with URI forgejo://owner/{owner} and MIME type application/json describing a Forgejo user or organization.

Scenario: Template appears in templates list

WHEN a client issues resources/templates/list
THEN the response SHALL include a template with uriTemplate = "forgejo://owner/{owner}"
AND the template's mimeType SHALL be application/json

Requirement: Owner resource read

resources/read for a forgejo://owner/{owner} URI SHALL return a JSON content block containing the owner's identity metadata: login, full_name, kind ("user" or "organization"), avatar_url, description, created_at. Fields absent from the upstream response SHALL be omitted from the JSON.

Scenario: Existing user resolves

WHEN a client reads forgejo://owner/goern
AND goern exists on the configured Forgejo instance
THEN the response SHALL contain one application/json content block
AND the JSON SHALL include login = "goern" and a kind field

Scenario: Missing owner returns -32003

WHEN a client reads forgejo://owner/does-not-exist
AND the upstream returns 404
THEN the server SHALL return MCP error code -32003

Requirement: Owner resource is not flagged as immutable

The owner template SHALL NOT carry a description claiming immutability. Owner metadata is mutable (display name, avatar, description can change).

Scenario: Description omits cache claim

WHEN a client inspects the owner template's description in resources/templates/list
THEN the description SHALL NOT contain the word "immutable" or "cacheable"

1.7 KiB Raw Permalink Blame History