coilyco-flight-deck/mcp-beaver

Watch

README names ward-mcp throughout while stating no relation to ward #75

New issue

Closed

opened 2026-08-16 00:26:30 +00:00 by coilyco-ops · 2 comments

coilyco-ops commented

2026-08-16 00:26:30 +00:00

Member

Problem

The README contradicts itself inside one screen. It states:

mcp-beaver has no relation to the ward codebase

Two paragraphs later, and throughout the Quickstart, the binary is ward-mcp:

go run ./cmd/ward-mcp serve examples/forgejo-issues.mcp.kdl --http :8080
"The generic ward-mcp serve runtime renders any .mcp.kdl"
"ward-mcp performs no inbound authentication"
"Guardfile auth configures ward-mcp's credential for the upstream service"
the curl example targets "repo":"ward-mcp"
the reserved info tool is ward_mcp_info

So a first-time reader meets three names for one thing (repo mcp-beaver, binary ward-mcp, tool ward_mcp_info) and an explicit denial of the relationship the naming implies. The most likely reading is that the docs are stale, which undermines trust in the rest of the page.

This is the first command a newcomer runs. On a 0-star repo it is plausibly the difference between trying the quickstart and closing the tab.

Why this is not a docs-only fix

Rewording the README without renaming the binary would make the docs lie. Renaming cmd/ward-mcp, the ward_mcp_info tool identifier, and any module paths changes identifiers and tool names, which is behavior and contract, not content.

Handing to Engineer rather than papering over it in prose.

Suggested resolution

Engineer decides whether the binary becomes mcp-beaver (or beaver), and whether ward_mcp_info follows.
If the tool identifier changes, that is an MCP contract change for any deployed server, so it needs its own compatibility note.
Once identifiers settle, the README prose and examples get updated to match in the same change.
If the names are staying as they are, then the "no relation to the ward codebase" sentence needs to explain the shared naming instead of denying it.

Filed from a portfolio promotion review. Sibling content-only issue covers the stale GitHub description.

## Problem The README contradicts itself inside one screen. It states: > mcp-beaver has **no relation to the ward codebase** Two paragraphs later, and throughout the Quickstart, the binary is `ward-mcp`: * `go run ./cmd/ward-mcp serve examples/forgejo-issues.mcp.kdl --http :8080` * "The generic `ward-mcp serve` runtime renders any `.mcp.kdl`" * "ward-mcp performs no inbound authentication" * "Guardfile `auth` configures ward-mcp's credential for the upstream service" * the curl example targets `"repo":"ward-mcp"` * the reserved info tool is `ward_mcp_info` So a first-time reader meets three names for one thing (repo `mcp-beaver`, binary `ward-mcp`, tool `ward_mcp_info`) and an explicit denial of the relationship the naming implies. The most likely reading is that the docs are stale, which undermines trust in the rest of the page. This is the first command a newcomer runs. On a 0-star repo it is plausibly the difference between trying the quickstart and closing the tab. ## Why this is not a docs-only fix Rewording the README without renaming the binary would make the docs lie. Renaming `cmd/ward-mcp`, the `ward_mcp_info` tool identifier, and any module paths changes identifiers and tool names, which is behavior and contract, not content. Handing to Engineer rather than papering over it in prose. ## Suggested resolution 1. Engineer decides whether the binary becomes `mcp-beaver` (or `beaver`), and whether `ward_mcp_info` follows. 2. If the tool identifier changes, that is an MCP contract change for any deployed server, so it needs its own compatibility note. 3. Once identifiers settle, the README prose and examples get updated to match in the same change. 4. If the names are staying as they are, then the "no relation to the ward codebase" sentence needs to explain the shared naming instead of denying it. Filed from a portfolio promotion review. Sibling content-only issue covers the stale GitHub description.

coilyco-ops added the

labels

2026-08-17 01:14:11 +00:00

coilyco-ops commented

2026-08-17 01:20:45 +00:00

Author

Member

Decision recorded by Darren (director seat), 2026-08-16, from a full triage pass of this repo. Kai's call in a consult round.

The call

Full rename, including the tool identifier. cmd/ward-mcp becomes cmd/beaver, and ward_mcp_info becomes beaver_info. The README then stops denying a relationship it no longer implies, because the naming that implied it is gone.

What was rejected, and why

Rename the binary only, freezing ward_mcp_info as a compatibility identifier. This was the recommended option and Kai declined it. It avoids the contract break and leaves a legacy name permanently embedded in every generated server's tool surface with a footnote explaining it. On a repo being actively promoted, a frozen wrong name is what a newcomer meets first.
Prose-only fix, keeping ward-mcp and explaining the shared heritage. Zero risk and it lands today. Declined because it keeps three names for one thing, which is the defect this issue reports.

What the call now requires

The tool identifier is an MCP contract. ward_mcp_info sits on every deployed server's surface and in every client roster that enumerates it, so this is coordinated work rather than a rename in one repo.

The rename here, binary and reserved tool both.
A compatibility note naming the old identifier and the release the new one lands in.
A roll of the generated fleet, since a client holding the old name gets a tool that no longer exists.
Regeneration of the mcporter inventories and native MCP registries that carry the old tool name, in the same batch.
README prose and every quickstart example updated in the same change.

Unresolved

Whether the Go module path and the Helm chart name follow the binary. Engineer's call and it does not block starting.

Relabelled priority/P2 autonomy/headless role/engineer role/ops. The blocking decision is discharged, so this leaves autonomy/async-consult.

**Decision recorded by Darren (director seat), 2026-08-16, from a full triage pass of this repo. Kai's call in a consult round.** ## The call **Full rename, including the tool identifier.** `cmd/ward-mcp` becomes `cmd/beaver`, and `ward_mcp_info` becomes `beaver_info`. The README then stops denying a relationship it no longer implies, because the naming that implied it is gone. ## What was rejected, and why * **Rename the binary only, freezing `ward_mcp_info` as a compatibility identifier.** This was the recommended option and Kai declined it. It avoids the contract break and leaves a legacy name permanently embedded in every generated server's tool surface with a footnote explaining it. On a repo being actively promoted, a frozen wrong name is what a newcomer meets first. * **Prose-only fix, keeping `ward-mcp` and explaining the shared heritage.** Zero risk and it lands today. Declined because it keeps three names for one thing, which is the defect this issue reports. ## What the call now requires The tool identifier is an MCP contract. `ward_mcp_info` sits on every deployed server's surface and in every client roster that enumerates it, so this is coordinated work rather than a rename in one repo. * The rename here, binary and reserved tool both. * A compatibility note naming the old identifier and the release the new one lands in. * A roll of the generated fleet, since a client holding the old name gets a tool that no longer exists. * Regeneration of the mcporter inventories and native MCP registries that carry the old tool name, in the same batch. * README prose and every quickstart example updated in the same change. ## Unresolved Whether the Go module path and the Helm chart name follow the binary. Engineer's call and it does not block starting. Relabelled `priority/P2` `autonomy/headless` `role/engineer` `role/ops`. The blocking decision is discharged, so this leaves `autonomy/async-consult`.

coilyco-ops added

and removed

labels

2026-08-17 01:21:50 +00:00

coilyco-ops referenced this issue from a commit

2026-08-17 02:24:22 +00:00

docs: explain the one surviving ward spelling instead of denying it (#75)

coilyco-ops closed this issue

2026-08-17 02:24:22 +00:00

coilyco-ops commented

2026-08-17 02:26:18 +00:00

Author

Member

Resolved on main in 3d9b6d2, taking option 4 from the issue.

The identifier half was already done before this: 299bda6 renamed the module, the binary to cmd/mcp-beaver, the chart, and the info tool to mcp_beaver_info, and the README names ward-mcp nowhere. What survived was the contradiction itself - a bare "no relation to the ward codebase" sitting a screen above wrap ward mcp forgejo, which reads as a stale doc rather than a deliberate boundary.

So the README and docs/DESIGN.md now name the one surviving spelling and say whose it is: wrap ward mcp <name> is umbra's inline grammar, it opens every deployed spec, and it moves when umbra moves. No compatibility note needed, because no tool identifier changed here.

Two things found while checking the sweep was real:

docs/DESIGN.md pointed both umbra links at github.com/coilysiren/cli-guard, the retired name #74 is about. Now canonical Forgejo.
The reader-facing resource examples taught ward:// URIs. The scheme is author-chosen and validates nothing, so an example is exactly where the dead name propagates. Now beaver://. Test fixtures keep theirs - nobody reads those as guidance.

Left alone deliberately, both already documented in AGENTS.md: nameOverride: ward-mcp in the chart, since a Kubernetes selector label is immutable, and the cli-guard v0.131.0 version reference in describe_test.go, which is a historical record.

Resolved on `main` in `3d9b6d2`, taking option 4 from the issue. The identifier half was already done before this: `299bda6` renamed the module, the binary to `cmd/mcp-beaver`, the chart, and the info tool to `mcp_beaver_info`, and the README names `ward-mcp` nowhere. What survived was the contradiction itself - a bare "no relation to the ward codebase" sitting a screen above `wrap ward mcp forgejo`, which reads as a stale doc rather than a deliberate boundary. So the README and `docs/DESIGN.md` now name the one surviving spelling and say whose it is: `wrap ward mcp <name>` is umbra's inline grammar, it opens every deployed spec, and it moves when umbra moves. No compatibility note needed, because no tool identifier changed here. Two things found while checking the sweep was real: * `docs/DESIGN.md` pointed both umbra links at `github.com/coilysiren/cli-guard`, the retired name #74 is about. Now canonical Forgejo. * The reader-facing `resource` examples taught `ward://` URIs. The scheme is author-chosen and validates nothing, so an example is exactly where the dead name propagates. Now `beaver://`. Test fixtures keep theirs - nobody reads those as guidance. Left alone deliberately, both already documented in `AGENTS.md`: `nameOverride: ward-mcp` in the chart, since a Kubernetes selector label is immutable, and the `cli-guard v0.131.0` version reference in `describe_test.go`, which is a historical record.

coilyco-ops referenced this issue from a commit

2026-08-17 02:31:23 +00:00

feat(instructions): let a guardfile say which dam you are at (#77)

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

coilyco-flight-deck/mcp-beaver#75

No description provided.

Rows
Columns