Skip to content

docs: fix two unfollowable instructions in fork docs (stale SDK pin, phantom runtime.ts bump) - #23

Merged
LDMB123 merged 2 commits into
mainfrom
debt/10x-docs-reality
Aug 2, 2026
Merged

docs: fix two unfollowable instructions in fork docs (stale SDK pin, phantom runtime.ts bump)#23
LDMB123 merged 2 commits into
mainfrom
debt/10x-docs-reality

Conversation

@LDMB123

@LDMB123 LDMB123 commented Aug 2, 2026

Copy link
Copy Markdown
Owner

Two docs-reality corrections found by a 10x tech-debt scan. Docs-only; no code, no behavior change, no dependency change.

1. docs/known-issues.md — SDK entry pins a version nine releases stale

The "MCP SDK 1.22.0 inline-stdio regression" entry's Status line still reads "pinned the SDK to ~1.21.2 until upstream ships a fix."

That pin has not been in effect for nine SDK releases:

Status line claims ~1.21.2
package.json @modelcontextprotocol/sdk: ^1.30.0
Installed 1.30.0
npm latest 1.30.0
Releases between 1.22.0 → 1.30.0 (9)

The pin was lifted in fefe54e"chore: bump sdk to 1.22.0 and adapt inline stdio test" — which also modified tests/cli-generate-cli.integration.test.ts, the very inline-stdio harness the entry's repro depends on.

Today a reader triaging a Cannot read properties of undefined (reading 'typeName') failure follows this entry to a remediation that isn't in place and a version floor the repo left long ago.

This PR deliberately does not claim the regression is fixed. Nobody has re-run the repro. Three possibilities remain live — fixed upstream, worked around when the harness was adapted, or simply no longer exercised — and the entry now names them as open and tells the reader to re-verify before relying on it. Marking it "fixed" would trade one false statement for another.

2. docs/RELEASE.md — step 1 names a file with no version to update

Step 1 said "Update version in package.json and src/runtime.ts." src/runtime.ts holds no version literal. It only re-exports:

import { MCPORTER_VERSION } from './version.js';
export { MCPORTER_VERSION } from './version.js';

and src/version.ts derives the value at runtime by require-ing package.json (falling back to $MCPORTER_VERSION, then '0.0.0-dev'). The version has exactly one source of truth and propagates on its own.

The instruction is unfollowable as written: a releaser either wastes time hunting for a literal that isn't there, or — worse — invents one and reintroduces exactly the drift version.ts exists to prevent. Dropping the phantom half.

Notes for the reviewer

  • Upstream-shared text. docs/RELEASE.md is heavily fork-delta (upstream's version is a different document), but the known-issues.md Status line is byte-identical to upstream/main — it is stale there too. Expect a conflict on the next upstream sync, and consider sending the correction upstream.
  • pnpm docs:site builds clean (exit 0). This repo does have PR CI (.github/workflows/ci.yml on pull_requestmain), so checks will run normally.

🤖 Generated with Claude Code

LDMB123 and others added 2 commits August 2, 2026 01:40
…ervation

The "MCP SDK 1.22.0 inline-stdio regression" entry's Status line still
says "pinned the SDK to ~1.21.2 until upstream ships a fix". That pin has
not existed for nine SDK releases: package.json now carries
`@modelcontextprotocol/sdk: ^1.30.0` (1.30.0 installed, 1.30.0 is
latest on npm). The pin was lifted in fefe54e ("chore: bump sdk to
1.22.0 and adapt inline stdio test"), which also touched the inline
stdio harness the repro depends on.

A reader triaging a `typeName` failure today would follow this entry to
a remediation that is not in place and a version floor the repo left
long ago.

Deliberately NOT claiming the regression is fixed — nobody has re-run
the repro. The three live possibilities (fixed upstream / worked around
in the test harness / no longer exercised) are named as open, and the
entry now tells the reader to re-verify before relying on it.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Release step 1 said "Update version in package.json and src/runtime.ts",
but src/runtime.ts holds no version literal to update. It only imports
and re-exports MCPORTER_VERSION from ./version.js:

  import { MCPORTER_VERSION } from './version.js';
  export { MCPORTER_VERSION } from './version.js';

and src/version.ts derives that value at runtime by require-ing
package.json (falling back to $MCPORTER_VERSION, then '0.0.0-dev'). The
version has exactly one source of truth — package.json — and it
propagates on its own.

The instruction is unfollowable as written: a releaser either wastes
time hunting for a literal that is not there, or worse, invents one and
reintroduces the drift version.ts exists to prevent.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@LDMB123
LDMB123 merged commit c7f53f6 into main Aug 2, 2026
3 checks passed
@LDMB123
LDMB123 deleted the debt/10x-docs-reality branch August 2, 2026 07:56
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant