From bc635110ad37bbebb4f189384a2b194843275dd2 Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 2 Aug 2026 11:31:51 +0000 Subject: [PATCH 1/2] Move REFERENCE.md to docs/REFERENCE.md Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01Rz1CPe5FWDQvMBNK5E96aP --- .github/workflows/release.yml | 2 +- CHANGELOG.md | 2 +- CLAUDE.md | 4 ++-- README.md | 2 +- REFERENCE.md => docs/REFERENCE.md | 2 +- scripts/generate-reference.mjs | 16 ++++++++-------- 6 files changed, 14 insertions(+), 14 deletions(-) rename REFERENCE.md => docs/REFERENCE.md (99%) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 7f4e4603..7c925404 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -292,7 +292,7 @@ jobs: NEW_VERSION="${{ steps.release.outputs.version }}" git config user.name "github-actions[bot]" git config user.email "41898282+github-actions[bot]@users.noreply.github.com" - git add package.json pnpm-lock.yaml CHANGELOG.md README.md REFERENCE.md + git add package.json pnpm-lock.yaml CHANGELOG.md README.md docs/REFERENCE.md git commit -m "v${NEW_VERSION}" git tag -a "v${NEW_VERSION}" -m "Release v${NEW_VERSION}" git push origin main diff --git a/CHANGELOG.md b/CHANGELOG.md index 71fe6a08..bdb075ec 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,7 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Added -- New [REFERENCE.md](REFERENCE.md) with the full `--help` output of every mcpc command, generated from the CLI itself so it always matches the release. +- New [REFERENCE.md](docs/REFERENCE.md) with the full `--help` output of every mcpc command, generated from the CLI itself so it always matches the release. - `mcpc @session` and `server-discover` now show the description and website URL a server advertises about itself, right below its name. ### Fixed diff --git a/CLAUDE.md b/CLAUDE.md index 25e7118d..f84266d6 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -161,7 +161,7 @@ mcpc/ - `mcpc clean [sessions|profiles|logs|all ...]` - Clean up mcpc data - `mcpc help [command]` - Show help for a specific command (`--skill` prints the agent guide) -Run `mcpc --help` and `mcpc help ` for the authoritative, always-current inventory — the usage block in README.md and the whole of REFERENCE.md are generated from it. +Run `mcpc --help` and `mcpc help ` for the authoritative, always-current inventory — the usage block in README.md and the whole of docs/REFERENCE.md are generated from it. **Server formats for `connect`, `login`, `logout`:** @@ -638,7 +638,7 @@ For any non-trivial change (new feature, bug fix, behaviour change, or notable r Whenever a change touches the user-facing CLI surface — adding, renaming, or removing commands or flags, changing argument syntax, defaults, session states, or workflows — check the agent skill at `skills/mcpc/SKILL.md` (printed by `mcpc help --skill`) and update it so it keeps matching the actual CLI behaviour and README. The skill is a curated guide, not an exhaustive reference: it must never contradict the CLI, but it doesn't need to enumerate every flag — keep it concise and only add features that matter to agents. Purely internal changes don't need a skill update; as a rule of thumb, any change that warrants a `CHANGELOG.md` entry also warrants a quick skill check. -Any change to help text — a description, an option, an `addHelpText` section, a new command — also changes `REFERENCE.md`, which is captured verbatim from `mcpc --help` and `mcpc help `. Never edit it by hand: run `pnpm run build:reference` and commit the result. CI runs `pnpm run check:reference` and fails when the committed file has drifted from the CLI, so this is not optional. +Any change to help text — a description, an option, an `addHelpText` section, a new command — also changes `docs/REFERENCE.md`, which is captured verbatim from `mcpc --help` and `mcpc help `. Never edit it by hand: run `pnpm run build:reference` and commit the result. CI runs `pnpm run check:reference` and fails when the committed file has drifted from the CLI, so this is not optional. Keep the MCP conformance tests up to date the same way you keep the e2e tests up to date. Whenever a change touches protocol behaviour, the OAuth/authentication flows, or transport handling, check `test/conformance/` in the same PR: update the adapter (`test/conformance/client.mjs`) if the change alters what a scenario observes, and wire up a matching upstream scenario when a new feature has one. Run the affected scenario locally before finishing — see `test/conformance/README.md` for the command, the current coverage table, and the list of scenarios that are not covered yet. A deliberate behaviour change that breaks the adapter must be fixed in the PR that makes the change, not discovered later when a release is gated on it. diff --git a/README.md b/README.md index 19936efc..a14ce80e 100644 --- a/README.md +++ b/README.md @@ -189,7 +189,7 @@ Run "mcpc --json" to get the same data as `{ sessions: [...], profiles: [...] }` Agent guide: mcpc help --skill ``` -For the full `--help` output of every command, see [REFERENCE.md](REFERENCE.md) +For the full `--help` output of every command, see [REFERENCE.md](docs/REFERENCE.md) (also available in your terminal via `mcpc help `). ### General actions diff --git a/REFERENCE.md b/docs/REFERENCE.md similarity index 99% rename from REFERENCE.md rename to docs/REFERENCE.md index 6b2b2feb..cd10ee8d 100644 --- a/REFERENCE.md +++ b/docs/REFERENCE.md @@ -6,7 +6,7 @@ Complete `--help` output for every `mcpc` command, in the order the commands are by `mcpc --help`. It is generated from the CLI itself, so it always matches the installed version — run `mcpc help ` to get the same text in your terminal. -New to mcpc? Start with the [README](README.md), or run `mcpc help --skill` for the agent guide. +New to mcpc? Start with the [README](../README.md), or run `mcpc help --skill` for the agent guide. - [`mcpc connect`](#mcpc-connect) - [`mcpc close`](#mcpc-close) diff --git a/scripts/generate-reference.mjs b/scripts/generate-reference.mjs index 75ee8b1a..792402d0 100644 --- a/scripts/generate-reference.mjs +++ b/scripts/generate-reference.mjs @@ -1,6 +1,6 @@ #!/usr/bin/env node /** - * Generates REFERENCE.md — the `--help` output of every mcpc command, in the order + * Generates docs/REFERENCE.md — the `--help` output of every mcpc command, in the order * the commands appear in `mcpc --help`. * * The CLI's help text is mcpc's primary documentation surface (see CLAUDE.md), so the @@ -9,8 +9,8 @@ * committed file has drifted from the CLI. * * Usage: - * node scripts/generate-reference.mjs Write REFERENCE.md - * node scripts/generate-reference.mjs --check Verify REFERENCE.md is up to date + * node scripts/generate-reference.mjs Write docs/REFERENCE.md + * node scripts/generate-reference.mjs --check Verify docs/REFERENCE.md is up to date */ import { execFileSync } from 'node:child_process'; @@ -21,7 +21,7 @@ import { fileURLToPath } from 'node:url'; const PROJECT_ROOT = dirname(dirname(fileURLToPath(import.meta.url))); const CLI = join(PROJECT_ROOT, 'bin', 'mcpc'); -const OUTPUT_FILE = join(PROJECT_ROOT, 'REFERENCE.md'); +const OUTPUT_FILE = join(PROJECT_ROOT, 'docs', 'REFERENCE.md'); /** * Placeholder session name used for the session command help screens. The CLI accepts it @@ -205,7 +205,7 @@ Complete \`--help\` output for every \`mcpc\` command, in the order the commands by \`mcpc --help\`. It is generated from the CLI itself, so it always matches the installed version — run \`mcpc help \` to get the same text in your terminal. -New to mcpc? Start with the [README](README.md), or run \`mcpc help --skill\` for the agent guide. +New to mcpc? Start with the [README](../README.md), or run \`mcpc help --skill\` for the agent guide. ${toc} @@ -226,13 +226,13 @@ if (checkOnly) { const current = existsSync(OUTPUT_FILE) ? readFileSync(OUTPUT_FILE, 'utf8') : ''; if (current !== generated) { console.error( - 'ERROR: REFERENCE.md is out of date with the CLI help output.\n' + + 'ERROR: docs/REFERENCE.md is out of date with the CLI help output.\n' + ' Run "pnpm run build:reference" and commit the result.' ); process.exit(1); } - console.log('REFERENCE.md is up to date.'); + console.log('docs/REFERENCE.md is up to date.'); } else { writeFileSync(OUTPUT_FILE, generated); - console.log(`REFERENCE.md updated (${generated.split('\n').length} lines).`); + console.log(`docs/REFERENCE.md updated (${generated.split('\n').length} lines).`); } From e8ba571b8f0fd83eb185aa4fce9eafb6035db0d8 Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 2 Aug 2026 11:31:57 +0000 Subject: [PATCH 2/2] Lower dependency release-age quarantine to 3 days, drop MCP SDK exemption The pinned @modelcontextprotocol packages are now all older than the quarantine window, so the minimumReleaseAgeExclude list is no longer needed. The release gate (scripts/check-dependency-age.mjs) reads its thresholds from pnpm-workspace.yaml, so it stays aligned automatically; its 48-hour floor mechanism remains for any future justified exemption. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01Rz1CPe5FWDQvMBNK5E96aP --- CONTRIBUTING.md | 6 +++--- pnpm-workspace.yaml | 21 +++++---------------- 2 files changed, 8 insertions(+), 19 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 510337ee..79ffd643 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -29,7 +29,7 @@ If your change touches the user-facing CLI surface (commands, flags, argument sy or workflows), also update the built-in agent skill at [`skills/mcpc/SKILL.md`](./skills/mcpc/SKILL.md) (printed by `mcpc help --skill`) so it keeps matching the CLI and README. -If your change touches any help text, regenerate [`REFERENCE.md`](./REFERENCE.md) with +If your change touches any help text, regenerate [`docs/REFERENCE.md`](./docs/REFERENCE.md) with `pnpm run build:reference` and commit it — it is captured verbatim from `mcpc --help` and `mcpc help `, and CI fails when it has drifted (`pnpm run check:reference`). @@ -57,8 +57,8 @@ pnpm link --global mcpc --help ``` -As a supply-chain hardening measure, `pnpm-workspace.yaml` sets `minimumReleaseAge: 7200`, so newly -published third-party packages aren't installed until they're at least 5 days old. If a fresh +As a supply-chain hardening measure, `pnpm-workspace.yaml` sets `minimumReleaseAge: 4320`, so newly +published third-party packages aren't installed until they're at least 3 days old. If a fresh dependency bump seems "stuck," that's why — wait it out, or add a targeted exclusion in `minimumReleaseAgeExclude` if you have a justified reason. diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml index 7ad5f95e..19c80ffc 100644 --- a/pnpm-workspace.yaml +++ b/pnpm-workspace.yaml @@ -1,24 +1,13 @@ # Supply-chain protection: require packages to be at least X days old before pnpm will install them. # Mitigates compromised npm packages discovered and yanked within the first day (shai-hulud worm, -# nx self-replicator, etc.). 7200 minutes = 5 days. -minimumReleaseAge: 7200 - -# The MCP TypeScript SDK ships fast and mcpc tracks it closely (the -# 2026-07-28 protocol support depends on the latest release), so exempt the SDK -# packages from the release-age gate. Scoped to the official -# @modelcontextprotocol org only; everything else keeps the 5-day quarantine. -# Remove entries once the pinned version is older than the age limit. +# nx self-replicator, etc.). 4320 minutes = 3 days. # # Note: pnpm 10 applies minimumReleaseAge only when *resolving*, and does not re-check an # existing lockfile on a --frozen-lockfile install (that landed in pnpm 11). The release -# gate in scripts/check-dependency-age.mjs enforces it over the committed lockfile, and -# holds the packages below to a 48-hour floor rather than exempting them outright. -minimumReleaseAgeExclude: - - "@modelcontextprotocol/client" - - "@modelcontextprotocol/core" - - "@modelcontextprotocol/server" - - "@modelcontextprotocol/node" - - "@modelcontextprotocol/sdk" +# gate in scripts/check-dependency-age.mjs enforces the same threshold over the committed +# lockfile at release time. If a package ever needs a justified exemption, add it to +# minimumReleaseAgeExclude — the release gate still holds excluded packages to a 48-hour floor. +minimumReleaseAge: 4320 # @napi-rs/keyring ships a native node binding that needs to be built/copied # into place on install. Without this entry pnpm v10 refuses to run its