MCP forks live in repos/frk/-mcp/; fixes go upstream via PR

rule Mon Jun 29 2026 00:00:00 GMT+0000 (Coordinated Universal Time) mcpforkfrkupstreamprhard-rule

MCP forks in `repos/frk/`

Rule

When the fleet uses an MCP server that requires modification or version-locking:

Fork the upstream repo to chirag127/<name>-mcp (preserves mcp-repo-naming-suffix).
Add as submodule at repos/frk/<name>-mcp/.
Work on the fork for local fixes.
PR upstream when the fix is generally useful.
Sync fork with upstream regularly per fork-discipline.
Smithery uploads point at the fork URL, not upstream.

When to fork vs use upstream

Situation	Action
Server works as-is on Smithery	Don't fork. Add to your Smithery toolbox. Lazy.
Server not on Smithery; works as-is from npm/PyPI	Don't fork. Use upstream package in `.mcp.json`.
Server broken / needs config knobs not exposed	Fork to `repos/frk/`, fix, PR upstream
Server abandoned / unresponsive maintainer	Fork to `repos/frk/`, maintain ourselves, don't bother with PR
Need to lock to a specific version for safety	Fork to `repos/frk/`, pin tag, don't auto-pull

Forking flow

gh repo fork <upstream>/<name>-mcp --org chirag127 --clone=false
cd C:\D\oriz
git submodule add https://github.com/chirag127/<name>-mcp repos/frk/<name>-mcp

After cloning, set the upstream remote:

cd repos/frk/<name>-mcp
git remote add upstream https://github.com/<upstream>/<name>-mcp
git fetch upstream

PR-upstream flow

When you fix a real bug:

cd repos/frk/<name>-mcp
git checkout -b fix/<short-slug>
# make changes, commit
git push origin fix/<short-slug>
gh pr create --repo <upstream>/<name>-mcp --base main --head chirag127:fix/<short-slug>

This satisfies both no-branches-on-own-repos (forks aren't "own repos") and the upstream-contribution norm.

Smithery uploads use fork URL

When uploading to Smithery toolbox @chirag127/toolbox:

Upload fork URL (https://github.com/chirag127/<name>-mcp), not upstream.
Smithery proxies HTTP MCPs and builds stdio MCPs in its container — pointing at our fork means Smithery rebuilds when we push to fork, not when upstream pushes.

Lazy gate

Per ponytail: don't fork preemptively. Only fork when:

You actually want to use the MCP, AND
It's NOT already on Smithery in working state, OR
It IS on Smithery but you need a modification.

If both conditions fail, use Smithery's hosted version of upstream. No fork needed.

Cross-refs

fork-discipline — general fork rules
mcp-repo-naming-suffix — naming
agent-fleet-parity — Smithery toolbox role
Runbook: upload-mcp-to-smithery-toolbox