docs: OpenSpec proposal for MCP resource templates #148
No reviewers
Labels
No labels
Compat/Breaking
Kind/Bug
Kind/Documentation
Kind/Enhancement
Kind/Feature
Kind/OpenSpec
Kind/Security
Kind/Testing
Priority/Critical
Priority/High
Priority/Low
Priority/Medium
RFC - Request For Comments
Reviewed/Confirmed
Reviewed/Duplicate
Reviewed/Invalid
Reviewed/Won't Fix
Status/Abandoned
Status/Blocked
Status/Need More Info
hermes-attempted
hermes-needs-clarification
hermes-ready
hermes-review
hermes-wip
human-required
No milestone
No project
No assignees
1 participant
Notifications
Due date
No due date set.
Dependencies
No dependencies set
Reference
agentic-forges/forgejo-mcp!148
Loading…
Reference in a new issue
No description provided.
Delete branch "refs/pull/148/head"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Summary
Adds the OpenSpec change
mcp-resource-templates— a design-only proposal for exposing seven core Forgejo entities as URI-addressable MCP resources alongside the existing tool surface.Entities:
owner,repo,commit,issue,pr,comment,status(combined CI status for a sha).No code changes. Implementation will follow under
/opsx:applyonce the proposal is reviewed.Why
forgejo-mcpis tool-only today. Core Forgejo entities are noun-like, sha- or index-addressable, and often immutable — natural MCP resource candidates. Exposing them as URI resources unlocks auto-resolution from LLM context (e.g. a sha in a PR diff resolves without an explicit tool call), content-addressable caching for immutable entities, and composable references between entities. Designing all seven at once avoids the inconsistent half-tool/half-resource state that a piecemeal rollout would create.Driven by bead
forgejo-mcp-1l5.Artifacts
openspec/changes/mcp-resource-templates/proposal.md— capability list for all 7 entities + impactopenspec/changes/mcp-resource-templates/design.md— 13 decisions (URI schemeforgejo://, coexist-vs-replace contract with existing tools, embedded-list bounding perdocs/design/output-bounding.md, caching annotations, auth + error mapping, client compatibility matrix, 6-slice rollout order)openspec/changes/mcp-resource-templates/specs/— 8 spec files (one per capability) with## ADDED Requirementsand#### Scenario:blocks; all scenarios testableopenspec/changes/mcp-resource-templates/tasks.md— 7 task groups (framework → commit → status → repo+owner → issue+comment → pr → docs/wrap)All 4 artifacts pass
openspec validate mcp-resource-templates --strict.Key Decisions (see design.md for full rationale)
forgejo://URI scheme (nothttps://…) — instance-portable, no collision with web links.WithResourceCapabilities(subscribe=false, listChanged=false)for v1 — read-on-demand only; subscriptions explicitly out of scope.RegisterResources(s)mirroring the existingRegisterXToolpattern; new sharedoperation/resource/package for URI parsing and bounding helpers.docs/design/output-bounding.mdwithout inventing a new query param onresources/read.text/markdownsidecar for entities carrying rendered text.mcp-resources-core+mcp-resource-commit(delivers value alone: replaces curl-for-statuses workflows).Out of Scope
/opsx:apply)resources/subscribeTest Plan
openspec validate mcp-resource-templates --strictpassesopenspec status --change mcp-resource-templatesshows 4/4 artifacts completedocs/design/output-bounding.mdCloses
forgejo-mcp-1l5.op1st Pipelines as Code/openspec-validate-pr-df9q6 is running.
Starting Pipelinerun openspec-validate-pr-df9q6 in namespace op1st-pipelines
You can monitor the execution using the op1st Pipelines as Code PipelineRun viewer or through the command line by
using the tkn CLI with the following command:
tkn pr logs -n op1st-pipelines openspec-validate-pr-df9q6 -fop1st Pipelines as Code/code-scans-vjtss is running.
Starting Pipelinerun code-scans-vjtss in namespace op1st-pipelines
You can monitor the execution using the op1st Pipelines as Code PipelineRun viewer or through the command line by
using the tkn CLI with the following command:
tkn pr logs -n op1st-pipelines code-scans-vjtss -fop1st Pipelines as Code/on-pull-request-sjnp7 is running.
Starting Pipelinerun on-pull-request-sjnp7 in namespace op1st-pipelines
You can monitor the execution using the op1st Pipelines as Code PipelineRun viewer or through the command line by
using the tkn CLI with the following command:
tkn pr logs -n op1st-pipelines on-pull-request-sjnp7 -fop1st Pipelines as Code/code-scans-vjtss has successfully validated your commit.
Task Statuses:
fetch-source
gitleaks-version
gitleaks
op1st Pipelines as Code/openspec-validate-pr-df9q6 has successfully validated your commit.
Task Statuses:
fetch-source
validate
op1st Pipelines as Code/on-pull-request-sjnp7 has successfully validated your commit.
Task Statuses:
fetch-source
build-and-test
op1st Pipelines as Code/code-scans-sdkvx is running.
Starting Pipelinerun code-scans-sdkvx in namespace op1st-pipelines
You can monitor the execution using the op1st Pipelines as Code PipelineRun viewer or through the command line by
using the tkn CLI with the following command:
tkn pr logs -n op1st-pipelines code-scans-sdkvx -fop1st Pipelines as Code/on-pull-request-5kwmg is running.
Starting Pipelinerun on-pull-request-5kwmg in namespace op1st-pipelines
You can monitor the execution using the op1st Pipelines as Code PipelineRun viewer or through the command line by
using the tkn CLI with the following command:
tkn pr logs -n op1st-pipelines on-pull-request-5kwmg -fop1st Pipelines as Code/openspec-validate-pr-44tgl is running.
Starting Pipelinerun openspec-validate-pr-44tgl in namespace op1st-pipelines
You can monitor the execution using the op1st Pipelines as Code PipelineRun viewer or through the command line by
using the tkn CLI with the following command:
tkn pr logs -n op1st-pipelines openspec-validate-pr-44tgl -fop1st Pipelines as Code/code-scans-sdkvx has successfully validated your commit.
Task Statuses:
fetch-source
gitleaks-version
gitleaks
op1st Pipelines as Code/openspec-validate-pr-44tgl has failed.
Task Statuses:
fetch-source
validate
Failure snippet:
task validate has the status "Failed":op1st Pipelines as Code/on-pull-request-5kwmg has failed.
Task Statuses:
fetch-source
build-and-test
commit-title-check
Failure snippet:
task commit-title-check has the status "Failed":op1st Pipelines as Code/code-scans-bdz6t is running.
Starting Pipelinerun code-scans-bdz6t in namespace op1st-pipelines
You can monitor the execution using the op1st Pipelines as Code PipelineRun viewer or through the command line by
using the tkn CLI with the following command:
tkn pr logs -n op1st-pipelines code-scans-bdz6t -fop1st Pipelines as Code/on-pull-request-2p5lm is running.
Starting Pipelinerun on-pull-request-2p5lm in namespace op1st-pipelines
You can monitor the execution using the op1st Pipelines as Code PipelineRun viewer or through the command line by
using the tkn CLI with the following command:
tkn pr logs -n op1st-pipelines on-pull-request-2p5lm -fop1st Pipelines as Code/openspec-validate-pr-7nq7q is running.
Starting Pipelinerun openspec-validate-pr-7nq7q in namespace op1st-pipelines
You can monitor the execution using the op1st Pipelines as Code PipelineRun viewer or through the command line by
using the tkn CLI with the following command:
tkn pr logs -n op1st-pipelines openspec-validate-pr-7nq7q -fop1st Pipelines as Code/code-scans-bdz6t has successfully validated your commit.
Task Statuses:
fetch-source
gitleaks-version
gitleaks
op1st Pipelines as Code/openspec-validate-pr-7nq7q has successfully validated your commit.
Task Statuses:
fetch-source
validate
op1st Pipelines as Code/on-pull-request-2p5lm has successfully validated your commit.
Task Statuses:
fetch-source
build-and-test
commit-title-check
Minutes — ready to merge
CI green on
cefe9ef026cfcc44a59caaca80936830dc53ec02:code-scans-bdz6t✅ (gitleaks)openspec-validate-pr-7nq7q✅on-pull-request-2p5lm✅ (build-and-test + commit-title-check)Final commit on this PR
fix: 🐛 openspec spec/release-tools-image add Purpose + Requirements headers— corrects the archived spec (introduced bybd92d21on main) that started with## ADDED Requirementsinstead of the conventional spec format. Without it,openspec validate --all --strictblocked every PR merging current main. Tracked via beadforgejo-mcp-1tc(closed).Scope unchanged
Proposal-only, no code. Implementation will follow under
/opsx:applyper the rollout order indesign.md(mcp-resources-core→mcp-resource-commitfirst).Merging.