forgejo-mcp/demos

forgejo-mcp Demos

End-to-end, copy-pasteable walkthroughs for the MCP tools shipped by forgejo-mcp. Each demo is a single Markdown file containing real ./forgejo-mcp --cli invocations against codeberg.org together with the output they produced — the same payload an MCP client would see.

How to read a demo

Every demo follows the same shape:

1. Background / What these tools do — the user-facing problem the feature solves and the tool surface it adds.
2. Setup — environment variables and the make build line. Identical across demos; once your shell is set up, skip it on subsequent reads.
3. Walkthrough — numbered, runnable shell blocks paired with the exact output produced. Where helpful, a Python one-liner formats the raw JSON envelope down to the fields that matter.
4. End-to-end / Autonomous workflow — how an agent strings the primitives together into a useful task (triage, review, time-track, etc.).

Demos use the CLI front-end (--cli <tool> --args '<json>') because it is the same code path as MCP tools/call but plays well with shell pipelines. Everything shown also works over stdio MCP and the streamable HTTP transport.

Setup once, run anywhere

export FORGEJO_URL=https://codeberg.org
export FORGEJO_ACCESS_TOKEN=<your-token>
make build

After that, every command in every demo starts with ./forgejo-mcp --cli.

---

Demos by topic

1. Issues, labels, milestones

Discovery and write tools for the core issue-tracking primitives. Autonomous agents need to map names → numeric IDs before they can call the mutating tools; the discovery demos cover that, the label demos cover the mutations.

Demo	Tools	What it shows
list-milestones-labels.md	list_repo_labels, list_repo_milestones	Discover the ID↔name mapping needed by add_issue_labels and update_issue
issue-labels.md	add_issue_labels, remove_issue_labels	Full add/remove cycle on a real issue, plus multi-label calls
org-labels.md	list_org_labels, merged list_repo_labels	Org-scope labels surfaced through the same ID space, with scope field and opt-out

Use case. Build a label lookup table once, then have the agent classify issues and apply labels without ever leaving the MCP loop.

2. Attachments

Forgejo lets users drop files on issues and on individual comments. These demos cover the full CRUD shape — list, get, download, create, edit, delete — for both surfaces.

Demo	Tools	What it shows
issue-attachments.md	6 tools keyed by index	Upload, inspect, download, rename, delete attachments on an issue/PR
comment-attachments.md	6 tools keyed by comment_id	Same lifecycle on individual comment attachments

Use case. An agent triaging a bug report needs to fetch the attached log file before reasoning about it; an agent writing a release note needs to attach a generated changelog to the release comment.

3. Releases

Tag-anchored release records and their binary assets. CRUD on releases (with a client-side state filter and target_commitish for new tags) plus the full attachment lifecycle on each release.

Demo	Tools	What it shows
release-management.md	14 tools — 8 release + 6 release-attachment	Read flow against goern/forgejo-mcp (list/latest/by-tag/state filter/list assets/over-cap download) plus the parameter surface for the write tools and the autonomous "draft notes for the next tag" workflow

Use case. A release-housekeeping agent that reads get_latest_release, summarises the commit log since published_at into Markdown notes, drafts the next release with create_release, optionally uploads built binaries with create_release_attachment, and waits for a human to flip draft=false via edit_release.

4. Time tracking

Forgejo carries a per-issue tracked-time ledger and a live stopwatch. Two demos split read/write of the ledger from the stopwatch transitions, because they are different mental models.

Demo	Tools	What it shows
issue-time-tracking.md	6 tools — list, add, delete, reset, user/repo aggregates	Manage the tracked-time ledger directly
issue-stopwatch.md	4 tools — start, stop, cancel, list mine	Drive the live stopwatch so the server computes the elapsed time

Use case. Agents that run long-lived tasks can record the time they actually spent without having to compute deltas themselves — start the stopwatch when work begins, stop it when work ends, let Forgejo do the math.

5. Notifications

Two demos: the lightweight "what's new" check, and the full notification-management API for marking read, fetching threads, and clearing inboxes.

Demo	Tools	What it shows
check-notifications.md	check_notifications	Read-only inbox poll across all watched repos
notifications-management.md	list/get/mark-read tools	100% notification API coverage — per-thread and bulk

Use case. A daily-standup agent that opens with "since yesterday, N notifications across M repos" and can clear them as it processes each one.

6. Organization management

Demo	Tools	What it shows
org-management.md	15 tools in the org domain	CRUD on the org itself, membership, and teams

Use case. Provisioning workflows — spin up a new org, add the team, attach repos, all from a single agent transcript with no web-UI clicks.

7. Code review (bounded I/O)

Demo	Tools	What it shows
bounded-responses.md	get_pull_request_diff with file_path, get_file_content with start_line/end_line	Cut payloads to just the file or line range the agent needs (measured 16× / 41× reductions on real data)

Use case. Reviewing a PR no longer means pulling the whole diff into the model's context. Pick one file's hunks, optionally read a few lines of surrounding source around each hunk, repeat. Per-call payloads stay proportional to what the agent actually inspects.

This is the user-facing half of the architectural rule in ../docs/design/output-bounding.md: every data-proportional response in this server must be bounded by the caller. Expect future tools to follow the same pattern.

8. Transport / infrastructure

Demo	Feature	What it shows
streamable-http-transport.md	--transport http	Run forgejo-mcp as a remote MCP server compatible with Claude.ai's custom-connector flow

Use case. Hosting a single forgejo-mcp instance behind an HTTPS endpoint and pointing multiple MCP clients at it, instead of every client spawning its own stdio subprocess.

9. Branch protection (governance)

CRUD on a repository's branch protection rules — require status checks or approvals before merge, and whitelist specific users (e.g. a release bot) to push to an otherwise locked branch. This demo is token-free: it proves the surface through the CLI tool registry and the httptest suite, since reading/writing real protection needs a repo-admin token. It is co-located with its spec under openspec/, not in this folder.

Demo	Tools	What it shows
../openspec/specs/branch-protection/branch-protection.demo.md	5 tools — list/get/create/edit/delete_branch_protection	Registration, the branch_name-required guard, push/merge/approvals whitelist params, and PATCH null-safety (unpassed fields never wipe an existing rule)

Use case. A governance agent that locks main, requires green CI before merge, and whitelists a release bot to push tags — without relaxing protection for anyone else.

---

Cross-cutting workflows

The demos individually cover single tool families. The interesting agent workflows compose across them:

• Autonomous issue triage. §1 (discover labels) → read issue body → §2 (fetch attachments if any) → §1 (apply labels) → §4 (start stopwatch if the agent will keep working on it).
• Code review. §7 (per-file diff slices + per-range file reads) → review-write tools (covered in the top-level README, not yet in a dedicated demo) → merge.
• Release housekeeping. §3 (draft notes via get_latest_release + commit log, then create_release with draft=true) → §5 (process notifications on the new release) → §6 (rotate team membership if needed).

Conventions

• scope field on labels. Returned by list_repo_labels and list_org_labels. "repo" or "org". Both can be passed to add_issue_labels without distinction.
• index vs comment_id. Issue/PR-level tools take index (the per-repo issue number). Comment-level tools take comment_id (the global comment ID returned by list_issue_comments).
• JSON envelope. CLI responses are an array of MCP Content blocks, e.g. [{"type":"text","text":"..."}]. Plain-text tools wrap the payload in a second {"Result":...} layer; the demo scripts unwrap both.
• Showboat stamps. The <!-- showboat-id: ... --> comment at the top of each demo lets the Showboat tool detect and refresh the file in place when the feature evolves.

Adding a new demo

When a new feature ships, add a demo file under demos/ and register it in the right section of this README. Keep the existing shape: background → setup → numbered walkthrough with output blocks → end-to-end workflow. Use real data from codeberg.org where possible so the numbers (sizes, counts, IDs) stay honest.