feat: CLI resource-read path (--cli read forgejo://...) for resource-template parity #191

New issue

Open

opened 2026-06-02 06:39:01 +00:00 by goern · 0 comments

goern commented

2026-06-02 06:39:01 +00:00

(Migrated from codeberg.org)

Problem

The --cli mode (cmd/cli.go) reaches tools but not resources.

Tools get CLI parity for free: RunCLI calls registerToolsWithDomains(mcpSrv) and cliExec dispatches by tool name. Any new tool is immediately forgejo-mcp --cli <tool> --args '{...}'.
Resources are not wired into --cli at all: registerToolsWithDomains registers tools only, and there is no forgejo:// reader / no read subcommand. So every forgejo:// resource-template is MCP-only and invisible from the CLI.

This is cross-cutting, not specific to one feature. It already affects the shipped resources (forgejo://repo/{owner}/{repo} repo, /commit/{sha}, /commit/{sha}/status, /issue/{index}, /pr/{index}, .../comment/{id}, forgejo://owner/{owner}) and blocks CLI parity for every future resource — concretely the webhook resources in #136 and the label resources in #190.

Proposed solution

Add a CLI resource-read command wired to the same resource handlers MCP uses:

forgejo-mcp --cli read <forgejo-uri> [--output json|text]

Register resources in --cli mode (a registerResourcesWithDomains paralleling registerToolsWithDomains, or reuse the existing RegisterResources* entry points).
read resolves the URI through the same template matching + handler path as resources/read over MCP — no duplicate logic, no second source of truth.
Honour the existing output-bounding contract (bounded embedded lists + truncation sentinel) identically to the MCP path.
--cli list (or a list-resources) should surface the registered resource-templates alongside tools, so the CLI is self-describing.

Why standalone

Both #136 (webhook resources) and #190 (label resources) carry a "CLI resource parity" sub-requirement. Solving it per-feature means re-deriving the same plumbing twice and leaving the already-shipped resources CLI-invisible. One reader, built once, gives parity to all current and future resource-templates. #136 and #190 depend on this.

Acceptance criteria

forgejo-mcp --cli read forgejo://repo/{owner}/{repo} returns the repo resource (proves the generic path on an already-shipped resource).
Resources registered in --cli mode via a shared entry point (no MCP-vs-CLI divergence in handlers).
Embedded-list bounding + truncation sentinel identical to the MCP resource path.
--cli list surfaces resource-templates (self-describing CLI).
README CLI section + AGENTS.md document --cli read.
Showboat demo reads at least one resource over --cli (parity proof for acceptance).

Blocks the resource-template halves of #136 and #190.
Tool CLI parity is already automatic; this closes the resource half.

## Problem The `--cli` mode (`cmd/cli.go`) reaches **tools** but not **resources**. - Tools get CLI parity for free: `RunCLI` calls `registerToolsWithDomains(mcpSrv)` and `cliExec` dispatches by tool name. Any new tool is immediately `forgejo-mcp --cli <tool> --args '{...}'`. - Resources are **not** wired into `--cli` at all: `registerToolsWithDomains` registers tools only, and there is no `forgejo://` reader / no `read` subcommand. So every `forgejo://` resource-template is MCP-only and invisible from the CLI. This is cross-cutting, not specific to one feature. It already affects the shipped resources (`forgejo://repo/{owner}/{repo}` repo, `/commit/{sha}`, `/commit/{sha}/status`, `/issue/{index}`, `/pr/{index}`, `.../comment/{id}`, `forgejo://owner/{owner}`) and blocks CLI parity for every future resource — concretely the webhook resources in #136 and the label resources in #190. ## Proposed solution Add a CLI resource-read command wired to the same resource handlers MCP uses: ``` forgejo-mcp --cli read <forgejo-uri> [--output json|text] ``` - Register resources in `--cli` mode (a `registerResourcesWithDomains` paralleling `registerToolsWithDomains`, or reuse the existing `RegisterResources*` entry points). - `read` resolves the URI through the same template matching + handler path as `resources/read` over MCP — no duplicate logic, no second source of truth. - Honour the existing output-bounding contract (bounded embedded lists + truncation sentinel) identically to the MCP path. - `--cli list` (or a `list-resources`) should surface the registered resource-templates alongside tools, so the CLI is self-describing. ## Why standalone Both #136 (webhook resources) and #190 (label resources) carry a "CLI resource parity" sub-requirement. Solving it per-feature means re-deriving the same plumbing twice and leaving the already-shipped resources CLI-invisible. One reader, built once, gives parity to all current and future resource-templates. #136 and #190 depend on this. ## Acceptance criteria - [ ] `forgejo-mcp --cli read forgejo://repo/{owner}/{repo}` returns the repo resource (proves the generic path on an already-shipped resource). - [ ] Resources registered in `--cli` mode via a shared entry point (no MCP-vs-CLI divergence in handlers). - [ ] Embedded-list bounding + truncation sentinel identical to the MCP resource path. - [ ] `--cli list` surfaces resource-templates (self-describing CLI). - [ ] README CLI section + `AGENTS.md` document `--cli read`. - [ ] Showboat demo reads at least one resource over `--cli` (parity proof for acceptance). ## Related - Blocks the resource-template halves of #136 and #190. - Tool CLI parity is already automatic; this closes the resource half.