agentic-forges/forgejo-mcp

Watch

Fork 0

docs: demos walkthrough for forgejo:// resource templates #173

Merged

goern merged 0 commits from refs/pull/173/head into main

2026-05-28 22:28:40 +00:00

goern commented

2026-05-28 17:24:46 +00:00

(Migrated from codeberg.org)

Summary

Adds demos/mcp-resource-templates.md — end-to-end walkthrough for all 7
resource templates shipped in #172 (owner, repo, commit, commit-status,
issue, pr, comment).

Follows the existing demos/README.md structure (see
demos/bounded-responses.md for style anchor). All captures are real
codeberg.org payloads against goern/forgejo-mcp.

Why

demos/ has one-file-per-feature walkthroughs for every other shipped
surface. Resource templates were the gap.
Closes part of OpenSpec task 1.11 in
openspec/changes/mcp-resource-templates/tasks.md (deferred manual
client verification).
Bead: forgejo-mcp-pkz.

Invocation

--cli mode covers tools only. Demo uses stdio JSON-RPC:

printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{...}}' \
  '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
  '{"jsonrpc":"2.0","id":N,"method":"resources/read","params":{"uri":"forgejo://..."}}' \
  | ./forgejo-mcp -t stdio -url "$FORGEJO_URL" -token "$FORGEJO_ACCESS_TOKEN" \
  | jq 'select(.id==N)'

Coverage

resources/templates/list — all 7 templates listed
forgejo://owner/{owner} — user/org dual-mode
forgejo://repo/{owner}/{repo} — identity + counts
forgejo://repo/{owner}/{repo}/commit/{sha} — JSON + markdown sidecar
forgejo://repo/{owner}/{repo}/commit/{sha}/status — combined CI state
forgejo://repo/{owner}/{repo}/issue/{index} — JSON + markdown sidecar
forgejo://repo/{owner}/{repo}/pr/{index} — embeds truncation sentinel example (PR #172 has 107 comments)
forgejo://repo/{owner}/{repo}/{kind}/{index}/comment/{id} — kind ∈ {issue, pr}
End-to-end autonomous read-only navigation pattern

Security

Tokens redacted; only commit SHAs appear in 40+ char regex matches
gitleaks v8.30.1 detect --no-git → no leaks found
All $FORGEJO_ACCESS_TOKEN references use env var, never inline

Test Plan

File renders correctly in markdown
All shell blocks executable against real codeberg.org
Output blocks match real captured responses
Spec link points to current (unarchived) location
Manual: try one URI from this demo against a fresh client (Claude Code, Desktop, Codex, Cursor) — closes task 1.11

Follow-ups (out of scope)

forgejo-mcp-7ra — subscribe=true support
forgejo-mcp-7de — embedded-list cap telemetry

## Summary Adds `demos/mcp-resource-templates.md` — end-to-end walkthrough for all 7 resource templates shipped in #172 (owner, repo, commit, commit-status, issue, pr, comment). Follows the existing `demos/README.md` structure (see `demos/bounded-responses.md` for style anchor). All captures are real codeberg.org payloads against `goern/forgejo-mcp`. ## Why - `demos/` has one-file-per-feature walkthroughs for every other shipped surface. Resource templates were the gap. - Closes part of OpenSpec task 1.11 in `openspec/changes/mcp-resource-templates/tasks.md` (deferred manual client verification). - Bead: `forgejo-mcp-pkz`. ## Invocation `--cli` mode covers tools only. Demo uses stdio JSON-RPC: ```bash printf '%s\n' \ '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{...}}' \ '{"jsonrpc":"2.0","method":"notifications/initialized"}' \ '{"jsonrpc":"2.0","id":N,"method":"resources/read","params":{"uri":"forgejo://..."}}' \ | ./forgejo-mcp -t stdio -url "$FORGEJO_URL" -token "$FORGEJO_ACCESS_TOKEN" \ | jq 'select(.id==N)' ``` ## Coverage - [x] `resources/templates/list` — all 7 templates listed - [x] `forgejo://owner/{owner}` — user/org dual-mode - [x] `forgejo://repo/{owner}/{repo}` — identity + counts - [x] `forgejo://repo/{owner}/{repo}/commit/{sha}` — JSON + markdown sidecar - [x] `forgejo://repo/{owner}/{repo}/commit/{sha}/status` — combined CI state - [x] `forgejo://repo/{owner}/{repo}/issue/{index}` — JSON + markdown sidecar - [x] `forgejo://repo/{owner}/{repo}/pr/{index}` — embeds truncation sentinel example (PR #172 has 107 comments) - [x] `forgejo://repo/{owner}/{repo}/{kind}/{index}/comment/{id}` — kind ∈ {issue, pr} - [x] End-to-end autonomous read-only navigation pattern ## Security - Tokens redacted; only commit SHAs appear in 40+ char regex matches - `gitleaks v8.30.1 detect --no-git` → no leaks found - All `$FORGEJO_ACCESS_TOKEN` references use env var, never inline ## Test Plan - [x] File renders correctly in markdown - [x] All shell blocks executable against real codeberg.org - [x] Output blocks match real captured responses - [x] Spec link points to current (unarchived) location - [ ] Manual: try one URI from this demo against a fresh client (Claude Code, Desktop, Codex, Cursor) — closes task 1.11 ## Follow-ups (out of scope) - `forgejo-mcp-7ra` — `subscribe=true` support - `forgejo-mcp-7de` — embedded-list cap telemetry

op1st-gitops commented

2026-05-28 17:24:53 +00:00

(Migrated from codeberg.org)

op1st Pipelines as Code/code-scans-4gm2j is running.

Starting Pipelinerun code-scans-4gm2j 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-4gm2j -f

op1st Pipelines as Code/code-scans-4gm2j is running. Starting Pipelinerun <b>[code-scans-4gm2j](https://console-openshift-console.apps.nostromo.erdgeschoss.b4mad.emea.operate-first.cloud/k8s/ns/op1st-pipelines/tekton.dev~v1~PipelineRun/code-scans-4gm2j)</b> in namespace <b>op1st-pipelines</b> You can monitor the execution using the [op1st Pipelines as Code](https://console-openshift-console.apps.nostromo.erdgeschoss.b4mad.emea.operate-first.cloud/k8s/ns/op1st-pipelines/tekton.dev~v1~PipelineRun/code-scans-4gm2j) PipelineRun viewer or through the command line by using the [tkn](https://tekton.dev/docs/cli/#installation) CLI with the following command: <code>tkn pr logs -n op1st-pipelines code-scans-4gm2j -f</code>

op1st-gitops commented

2026-05-28 17:24:53 +00:00

(Migrated from codeberg.org)

op1st Pipelines as Code/on-pull-request-t4lzm is running.

Starting Pipelinerun on-pull-request-t4lzm 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-t4lzm -f

op1st Pipelines as Code/on-pull-request-t4lzm is running. Starting Pipelinerun <b>[on-pull-request-t4lzm](https://console-openshift-console.apps.nostromo.erdgeschoss.b4mad.emea.operate-first.cloud/k8s/ns/op1st-pipelines/tekton.dev~v1~PipelineRun/on-pull-request-t4lzm)</b> in namespace <b>op1st-pipelines</b> You can monitor the execution using the [op1st Pipelines as Code](https://console-openshift-console.apps.nostromo.erdgeschoss.b4mad.emea.operate-first.cloud/k8s/ns/op1st-pipelines/tekton.dev~v1~PipelineRun/on-pull-request-t4lzm) PipelineRun viewer or through the command line by using the [tkn](https://tekton.dev/docs/cli/#installation) CLI with the following command: <code>tkn pr logs -n op1st-pipelines on-pull-request-t4lzm -f</code>

op1st-gitops commented

2026-05-28 17:25:13 +00:00

(Migrated from codeberg.org)

op1st Pipelines as Code/code-scans-4gm2j has successfully validated your commit.

Namespace: op1st-pipelines
PipelineRun: code-scans-4gm2j

Task Statuses:

Status	Duration	Name
Succeeded	10 seconds	fetch-source
Succeeded	6 seconds	gitleaks-version
Succeeded	10 seconds	gitleaks

op1st Pipelines as Code/code-scans-4gm2j has <b>successfully</b> validated your commit. <ul> <li><b>Namespace</b>: <a href="https://detailurl.setting.custom-console-url-namespace.is.not.configured">op1st-pipelines</a></li> <li><b>PipelineRun:</b> <a href="https://console-openshift-console.apps.nostromo.erdgeschoss.b4mad.emea.operate-first.cloud/k8s/ns/op1st-pipelines/tekton.dev~v1~PipelineRun/code-scans-4gm2j">code-scans-4gm2j</a></li> </ul> <hr> <h4>Task Statuses:</h4> <table> <tr><th>Status</th><th>Duration</th><th>Name</th></tr> <tr> <td>Succeeded</td> <td>10 seconds</td><td> [fetch-source](https://console-openshift-console.apps.nostromo.erdgeschoss.b4mad.emea.operate-first.cloud/k8s/ns/op1st-pipelines/tekton.dev~v1~PipelineRun/code-scans-4gm2j/logs/fetch-source) </td></tr> <tr> <td>Succeeded</td> <td>6 seconds</td><td> [gitleaks-version](https://console-openshift-console.apps.nostromo.erdgeschoss.b4mad.emea.operate-first.cloud/k8s/ns/op1st-pipelines/tekton.dev~v1~PipelineRun/code-scans-4gm2j/logs/gitleaks-version) </td></tr> <tr> <td>Succeeded</td> <td>10 seconds</td><td> [gitleaks](https://console-openshift-console.apps.nostromo.erdgeschoss.b4mad.emea.operate-first.cloud/k8s/ns/op1st-pipelines/tekton.dev~v1~PipelineRun/code-scans-4gm2j/logs/gitleaks) </td></tr> </table>

op1st-gitops commented

2026-05-28 17:27:13 +00:00

(Migrated from codeberg.org)

op1st Pipelines as Code/on-pull-request-t4lzm has successfully validated your commit.

Namespace: op1st-pipelines
PipelineRun: on-pull-request-t4lzm

Task Statuses:

Status	Duration	Name
Succeeded	11 seconds	fetch-source
Succeeded	15 seconds	commit-title-check
Succeeded	2 minutes	build-and-test

op1st Pipelines as Code/on-pull-request-t4lzm has <b>successfully</b> validated your commit. <ul> <li><b>Namespace</b>: <a href="https://detailurl.setting.custom-console-url-namespace.is.not.configured">op1st-pipelines</a></li> <li><b>PipelineRun:</b> <a href="https://console-openshift-console.apps.nostromo.erdgeschoss.b4mad.emea.operate-first.cloud/k8s/ns/op1st-pipelines/tekton.dev~v1~PipelineRun/on-pull-request-t4lzm">on-pull-request-t4lzm</a></li> </ul> <hr> <h4>Task Statuses:</h4> <table> <tr><th>Status</th><th>Duration</th><th>Name</th></tr> <tr> <td>Succeeded</td> <td>11 seconds</td><td> [fetch-source](https://console-openshift-console.apps.nostromo.erdgeschoss.b4mad.emea.operate-first.cloud/k8s/ns/op1st-pipelines/tekton.dev~v1~PipelineRun/on-pull-request-t4lzm/logs/fetch-source) </td></tr> <tr> <td>Succeeded</td> <td>15 seconds</td><td> [commit-title-check](https://console-openshift-console.apps.nostromo.erdgeschoss.b4mad.emea.operate-first.cloud/k8s/ns/op1st-pipelines/tekton.dev~v1~PipelineRun/on-pull-request-t4lzm/logs/commit-title-check) </td></tr> <tr> <td>Succeeded</td> <td>2 minutes</td><td> [build-and-test](https://console-openshift-console.apps.nostromo.erdgeschoss.b4mad.emea.operate-first.cloud/k8s/ns/op1st-pipelines/tekton.dev~v1~PipelineRun/on-pull-request-t4lzm/logs/build-and-test) </td></tr> </table>

goern commented

2026-05-28 21:18:01 +00:00

(Migrated from codeberg.org)

Minutes

Scheduled merge-when-green via merge_pull_request with style=merge, delete_branch_after_merge=true.

Workflow used: sonnet drafted from brief in worktree demo-resource-templates; opus validated against openspec/changes/mcp-resource-templates/specs/mcp-resources-core/spec.md and operation/ source. Two issues caught + fixed before commit:

Broken spec link — pointed at archived path openspec/specs/mcp-resources-core/spec.md which only exists post-archive; corrected to current change path.
Cosmetic truncated: null in jq projection for commit-status (the omitempty field drops out when false); rewrote projection and added inline note about the field's natural absence.

Security: gitleaks v8.30.1 detect --no-git returned no leaks found. Regex scrub [a-zA-Z0-9_-]{40,} matched only commit SHAs + showboat slug. $FORGEJO_ACCESS_TOKEN always passed via env var, never inline.

Verification: all 7 captures real against goern/forgejo-mcp on codeberg.org. JSON-RPC handshake (protocolVersion: 2024-11-05 + notifications/initialized) exercised once per section so each block is copy-paste-runnable in isolation.

Bead forgejo-mcp-pkz closing on merge.

## Minutes Scheduled merge-when-green via `merge_pull_request` with `style=merge`, `delete_branch_after_merge=true`. **Workflow used**: sonnet drafted from brief in worktree `demo-resource-templates`; opus validated against `openspec/changes/mcp-resource-templates/specs/mcp-resources-core/spec.md` and `operation/` source. Two issues caught + fixed before commit: 1. Broken spec link — pointed at archived path `openspec/specs/mcp-resources-core/spec.md` which only exists post-archive; corrected to current change path. 2. Cosmetic `truncated: null` in `jq` projection for commit-status (the `omitempty` field drops out when false); rewrote projection and added inline note about the field's natural absence. **Security**: `gitleaks v8.30.1 detect --no-git` returned `no leaks found`. Regex scrub `[a-zA-Z0-9_-]{40,}` matched only commit SHAs + showboat slug. `$FORGEJO_ACCESS_TOKEN` always passed via env var, never inline. **Verification**: all 7 captures real against `goern/forgejo-mcp` on codeberg.org. JSON-RPC handshake (`protocolVersion: 2024-11-05` + `notifications/initialized`) exercised once per section so each block is copy-paste-runnable in isolation. Bead `forgejo-mcp-pkz` closing on merge.

No reviewers

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference

agentic-forges/forgejo-mcp!173

No description provided.

Rows
Columns