charles/claude-hooks
1
0
Fork 0
Code Issues 10 Pull requests Projects Releases Packages 1 Wiki Activity Actions

MF-5: Forge-neutral MCP namespace (mcp__forge__*) #296

New issue
Closed
opened 2026-04-23 23:33:14 +00:00 by code-lead · 0 comments
code-lead commented 2026-04-23 23:33:14 +00:00
Collaborator
Copy link

As a skill/agent author, I want a single forge-neutral MCP namespace (mcp__forge__*) so that the same skill runs unchanged against any configured forge — the agent never has to know whether the repo lives on Forgejo, GitHub, or GitLab.

Acceptance criteria

Decision (documented inline)

  • Choose option (a): one forge-neutral MCP server backed by the ForgePort adapter bound to the agent's repo. Not per-forge MCPs.
  • Rationale captured in the package README: one surface to maintain, adapters already exist, no duplicated upstream MCP deps.

New MCP package

  • New workspace package: packages/forge-mcp/.
  • Exposes stdio MCP implementing the forge-neutral tool set:
    • forge__create_issue
    • forge__get_issue_by_index
    • forge__list_repo_issues
    • forge__add_issue_labels
    • forge__remove_issue_labels
    • forge__update_issue
    • forge__create_issue_comment
    • forge__list_issue_comments
    • forge__create_pull_request
    • forge__get_pull_request_by_index
    • forge__list_repo_pull_requests
    • forge__list_pull_request_files
    • forge__create_pull_review
    • forge__create_review_requests
    • forge__delete_review_requests
    • forge__submit_pull_review
    • forge__list_pull_reviews
    • forge__list_pull_review_comments
    • forge__get_pull_review
    • forge__merge_pull_request
    • forge__get_file_content
    • forge__get_workflow_run
    • forge__list_workflow_runs
    • forge__list_repo_labels
    • (1:1 with the ForgePort surface used by today's skills.)
  • Internal resolution: FORGE_TYPE env (forgejo|github|gitlab) + per-forge token file path select the adapter at MCP startup.

Container wiring

  • Agent containers mount packages/forge-mcp in place of (or, during the transition window, alongside) forgejo-mcp.
  • Container-reconcile and the env-sync watchdog both know about the new MCP binary path.

Skill migration

  • All repo-owned skills updated to the forge__* tool names: breakdown, design-implement, review, implement, security-review, revise-claude-md.
  • Tool-schema allowlists in .claude/settings.json (or equivalent) include the new namespace.

Transitional alias

  • forgejo-mcp stays installed for one release so any unmigrated skill keeps working.
  • When the old namespace is called, log a deprecation warning once per session (rate-limited).

Tests

  • forge-mcp.test.ts: each tool call maps to the correct ForgePort method with the env-selected adapter (Forgejo/GitHub via stub).
  • Skill smoke test: breakdown runs end-to-end against a fake GitHub ForgePort.
  • Deprecation warning fires exactly once for a call to mcp__forgejo__create_issue.

Out of scope

  • Deprecating mcp__forgejo__*-named skills that live outside this repo — other owners migrate on their own timeline.
  • Penpot / Context7 / other MCPs — unrelated, untouched.
  • Adding new capabilities to the port beyond what today's skills use.

References

  • Spec: specs/multi-forge.md § MF-5.
  • packages/shared/ — cross-app types.
  • Existing skills that call mcp__forgejo__* (grep the skills/ tree).
  • Open decision captured in the spec: rename vs alias — this story lands on rename.

Dependencies

  • Blocks on MF-4 (adapter factory) — the MCP resolves the adapter via the factory at startup.
  • Blocks on MF-1 (at least one non-Forgejo adapter). Server-side MCP code can begin earlier, but end-to-end skill migration requires a second adapter live.
  • Depends on #295 (MF-4)
  • Depends on #292 (MF-1)
As a skill/agent author, I want a single forge-neutral MCP namespace (`mcp__forge__*`) so that the same skill runs unchanged against any configured forge — the agent never has to know whether the repo lives on Forgejo, GitHub, or GitLab. ## Acceptance criteria ### Decision (documented inline) - [ ] Choose option **(a)**: one forge-neutral MCP server backed by the `ForgePort` adapter bound to the agent's repo. Not per-forge MCPs. - [ ] Rationale captured in the package README: one surface to maintain, adapters already exist, no duplicated upstream MCP deps. ### New MCP package - [ ] New workspace package: `packages/forge-mcp/`. - [ ] Exposes stdio MCP implementing the forge-neutral tool set: - `forge__create_issue` - `forge__get_issue_by_index` - `forge__list_repo_issues` - `forge__add_issue_labels` - `forge__remove_issue_labels` - `forge__update_issue` - `forge__create_issue_comment` - `forge__list_issue_comments` - `forge__create_pull_request` - `forge__get_pull_request_by_index` - `forge__list_repo_pull_requests` - `forge__list_pull_request_files` - `forge__create_pull_review` - `forge__create_review_requests` - `forge__delete_review_requests` - `forge__submit_pull_review` - `forge__list_pull_reviews` - `forge__list_pull_review_comments` - `forge__get_pull_review` - `forge__merge_pull_request` - `forge__get_file_content` - `forge__get_workflow_run` - `forge__list_workflow_runs` - `forge__list_repo_labels` - (1:1 with the `ForgePort` surface used by today's skills.) - [ ] Internal resolution: `FORGE_TYPE` env (`forgejo|github|gitlab`) + per-forge token file path select the adapter at MCP startup. ### Container wiring - [ ] Agent containers mount `packages/forge-mcp` in place of (or, during the transition window, alongside) `forgejo-mcp`. - [ ] Container-reconcile and the env-sync watchdog both know about the new MCP binary path. ### Skill migration - [ ] All repo-owned skills updated to the `forge__*` tool names: `breakdown`, `design-implement`, `review`, `implement`, `security-review`, `revise-claude-md`. - [ ] Tool-schema allowlists in `.claude/settings.json` (or equivalent) include the new namespace. ### Transitional alias - [ ] `forgejo-mcp` stays installed for one release so any unmigrated skill keeps working. - [ ] When the old namespace is called, log a deprecation warning once per session (rate-limited). ### Tests - [ ] `forge-mcp.test.ts`: each tool call maps to the correct `ForgePort` method with the env-selected adapter (Forgejo/GitHub via stub). - [ ] Skill smoke test: `breakdown` runs end-to-end against a fake GitHub `ForgePort`. - [ ] Deprecation warning fires exactly once for a call to `mcp__forgejo__create_issue`. ## Out of scope - Deprecating `mcp__forgejo__*`-named skills that live outside this repo — other owners migrate on their own timeline. - Penpot / Context7 / other MCPs — unrelated, untouched. - Adding new capabilities to the port beyond what today's skills use. ## References - Spec: [`specs/multi-forge.md`](../src/branch/main/specs/multi-forge.md) § MF-5. - `packages/shared/` — cross-app types. - Existing skills that call `mcp__forgejo__*` (grep the `skills/` tree). - Open decision captured in the spec: rename vs alias — this story lands on rename. ## Dependencies - **Blocks on MF-4** (adapter factory) — the MCP resolves the adapter via the factory at startup. - **Blocks on MF-1** (at least one non-Forgejo adapter). Server-side MCP code can begin earlier, but end-to-end skill migration requires a second adapter live. <!-- machine-parseable deps for the deps.ts body fallback; native POST /dependencies is currently returning HTTP 404 on this Forgejo. --> - Depends on #295 (MF-4) - Depends on #292 (MF-1)
Sign in to join this conversation.
No Branch/Tag specified
Branches Tags
main
chore/sync-pre-push-from-forge-base
fix/flows-yaml-dispatch-identity
feat/board-tap-to-assign
dev/1107
code-lead/1106
code-lead/1108
dev/1104
code-lead/1103
code-lead/1080
dev/1087
feat/flows-yaml-ci-events
chore/board-drop-stalled-and-density-controls
fix/flows-yaml-routes-always-register
flows-yaml/api-defaults
dev/1023
fix/event-log-history-bleed
fix/janitor-fix-ci-logs-and-cap
dev/1022
fix/board-card-provider
code-lead/1036
dev/1025
code-lead/1020
dev/1017
code-lead/1026
feat/web-shortcut-registry-1018
dev/1015
code-lead/1009
code-lead/1008
dev/975
dev/969
dev/973
dev/967
code-lead/968
code-lead/953
dev/970
dev/976
code-lead/966
code-lead/956
code-lead/951
dev/962
dev/963
dev/977
dev/955
dev/983
dev/961
dev/974
code-lead/950
code-lead/939
dev/941
dev/940
dev/937
dev/938
dev/936
dev/935
feat/web-i18n-fr-locale
feat/spec-editor-ui-polish
chore/drop-legacy-compat
fix/skills-drop-preview-pane
fix/882-skills-safety-rail
dev/911
dev/909
dev/923
dev/917
dev/915
feat/879-sr11-m2-drop-legacy-skill
code-lead/873
dev/881
code-lead/869
dev/867
code-lead/845
code-lead/843
code-lead/844
dev/837
dev/861
dev/849
code-lead/837
code-lead/842
fix/dedup-rebase-inflight
dev/838
code-lead/847
dev/833
code-lead/848
pr/838
code-lead/841
feat/settings-save-bar/836
code-lead/840
dev/846
code-lead/839
dev/832
fix/board-sse-stale-cache
dev/834
dev/835
feat/settings-breadcrumbs
feat/forge-oauth-credentials
refactor/service-config-consolidation
feat/agent-tokens-to-secrets
feat/gitlab-oauth-to-db
feat/authelia-rip-and-voice-fixes
fix/rebase-storm-and-dead-letter
code-lead/797
code-lead/796
dev/811
code-lead/798
dev/810
code-lead/795
dev/808
code-lead/794
dev/805
dev/802
dev/803
feat/avatar-menu-settings-entry
feat/per-agent-token-tracking
dev/793
dev/747
dev/752
code-lead/790
code-lead/759
dev/756
dev/760
dev/741
dev/767
dev/740
dev/709
dev/644
dev/637
boss/614
dev/600
dev/611
dev/585
fix/login-bonus-fixes
boss/544
dev/542
refactor/api-prefix-and-session-gate
dev/489
boss/531
boss/518
dev/499
boss/516
dev/530
dev/517
dev/519
dev/515
dev/522
dev/503
dev/471
boss/329
dev/417
dev/418
dev/402
boss/327
dev/334
dev/332
boss/326
boss/325
dev/331
boss/324
boss/323
boss/322
dev/294
test/s11-task-analytics
dev/262
boss/270
dev/268
foreman/ui-consolidation-spec
dev/234
boss/196
boss/176
boss/164
fix/124-session-persist-bind
boss/52
dev/87
boss/73
dev/77
dev/81
dev/82
boss/79
dev/42
dev/35
boss/7
No results found.
Labels
Clear labels   
area:agents
Agent types, pool scheduling, per-instance config

  
area:dashboard
Dashboard UI and observability surfaces

  
area:database
DB layer — schema, migrations, ORM, raw SQL

  
area:design
UI/UX mockup work — routes to designer agent

  
area:design-review
Design review dispatch — routes to design-reviewer agent

  
area:flows
Flow runner — YAML loader, executor, op registry, expression eval

  
area:infra
Deployment, isolation, containers, systemd units

  
area:meta
Tracking, scaffolding, project setup

  
area:security
Security — routes to reviewer-security (opus)

  
area:sessions
Session-id store, Claude SDK resume logic

  
area:webhook
Forgejo webhook routing and handlers

  
area:workdir
Clone cache, worktrees, git identity

  
security
Security-sensitive issue

  
type:bug
Bug

  
type:chore
Chore

  
type:meta
Tracking or decisions, not implementation work

  
type:user-story
User story

No labels
area:agents
area:dashboard
area:database
area:design
area:design-review
area:flows
area:infra
area:meta
area:security
area:sessions
area:webhook
area:workdir
security
type:bug
type:chore
type:meta
type:user-story
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
code-lead
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
charles/claude-hooks#296
No description provided.