Migrate Git Workflow MCP server to dual-era stdio negotiation #2426

Decision: TEST

Change

On 2026-10-12, the official MCP repository changed its TypeScript server quickstart to use serveStdio(createServer) and explicitly documented that hand-wiring server.connect(new StdioServerTransport()) only serves 2025-era clients.

• Official commit: modelcontextprotocol/modelcontextprotocol@3778656
• Official modern verification command: npx @modelcontextprotocol/inspector --cli <command> --protocol-era modern --method tools/list
• The Inspector defaults to the legacy era, so modern and legacy must both be tested.

Verified EventRelay fit

At protected main commit 002b697c3c5c6cb208c24e1b3413f13f1a2a8794:

• tools/mcp/git_workflow_server.mjs imports StdioServerTransport and calls await this.server.connect(transport).
• package.json uses the monolithic @modelcontextprotocol/sdk@^1.30.1, whereas the new official example uses the split @modelcontextprotocol/server package.
• No open issue was found for serveStdio, the Git Workflow MCP server, or this compatibility requirement.

This proves an actionable compatibility gap in the current wiring. It does not prove the server is deployed or that a production client has failed.

Shortest practical build

1. Capture current behavior before changing dependencies

Add a pinned Inspector dev dependency using the exact official package version selected in the implementation PR; do not use an unpinned network install in CI.

After npm ci, run:

npx --no-install @modelcontextprotocol/inspector --cli   node tools/mcp/git_workflow_server.mjs   --protocol-era legacy --method tools/list

npx --no-install @modelcontextprotocol/inspector --cli   node tools/mcp/git_workflow_server.mjs   --protocol-era modern --method tools/list

Record exit status, stderr, negotiated protocol revision, and tool names without invoking any git mutation. The legacy baseline is expected to list six tools. The modern baseline is expected to fail until migrated; if it already passes, stop and investigate rather than forcing the change.

2. Migrate through the supported package boundary

• Resolve and pin compatible exact versions of @modelcontextprotocol/server, @modelcontextprotocol/core, and the Inspector from official releases.
• Refactor server construction into a side-effect-free createServer() factory returning a fresh instance.
• Replace hand-wired transport startup with serveStdio(createServer, { onerror }).
• Preserve the six existing tool contracts and error semantics.
• Do not copy a documentation example blindly: the current server uses the v1 low-level Server API, so confirm each registration and error-code mapping against the selected v2 API.

3. Add deterministic regression coverage

Create fixture tests that:

1. Run tools/list in both modern and legacy protocol eras.
2. Require exactly git_status, git_diff, git_add, git_commit, git_push, and git_pull.
3. Set GIT_WORKSPACE_ROOT to a temporary initialized repository.
4. Prove tools/list does not modify the repository.
5. Prove a modern discovery probe can be discarded and a legacy initialize can create a fresh server instance.
6. Keep network disabled and never call push, pull, commit, or credential-bearing paths.

Run:

npm ci
npm test -- --runInBand
npm run lint
npm run build
git diff --check

Use the repository's actual focused test command if it differs; record it in the PR receipt.

Verification

Status: NOT RUN

Smallest meaningful acceptance test:

• modern Inspector lists the same six tools as legacy;
• neither run changes git status --porcelain;
• CI, security, dependency review, secret scanning, and exact-head tests pass;
• no live remote, credentials, push, pull, deployment, or production registration is used.

Cost, effort, and rollback

• Fixture work: $0.
• ESTIMATE: 4–8 engineering hours, mainly because this is a v1-to-v2 package/API boundary rather than a one-line transport edit.
• Rollback before merge: close the draft PR and delete its branch.
• Rollback after merge: revert the exact merge commit and restore the previously pinned SDK lockfile.

Product opportunity

Once verified, the dual-era compatibility fixture can become part of the supervised MCP Compatibility Audit deliverable for teams migrating servers to the 2026-07-28 protocol. Revenue remains a hypothesis until paid evidence exists.

Boundaries

No package was installed, server executed, git mutation invoked, deployment performed, production registration changed, money spent, or merge attempted in creating this recipe.