Preserve versioned STDIO API user agents across MCP protocols

[jidicula]

Summary

Give STDIO GitHub API requests a server/version user agent before any MCP handshake, retaining upstream client metadata per request across legacy and modern MCP protocols. Resolve usable build metadata for version-specific attribution without making missing or malformed metadata prevent startup.

Why

The pinned MCP SDK permits discovery and direct metadata-bearing tool calls without initialize, so initialisation-only middleware misses those requests. Reading ClientInfo() per request also avoids mutating a shared transport when client identity changes.

What changed

• Set a default versioned GraphQL user agent and apply escaped upstream client metadata through request context. Preserve existing remote-server defaults, insiders markers, authentication and GraphQL feature headers.
• Select valid version metadata in order: explicit release, explicit source revision, embedded VCS revision, then installed main-module version. Use vcs-<full-sha> for revisions, applying -dirty only to embedded VCS metadata. If nothing is usable, start with dev and warn on stderr, keeping stdout available for MCP.
• Cover protocol negotiation, direct calls, concurrent transport isolation and version precedence/fallbacks. Document the version contract and whole-package build command.

MCP impact

• No tool or API changes: schemas, tool results and permissions are unchanged. The additive exported transport-context helper preserves existing defaults.
• Tool schema or behaviour changed
• New tool added

Prompts tested (tool changes only)

Not applicable; tool definitions and schemas are unchanged.

Security / limits

• No security or limits impact
• Auth / permissions considered: existing bearer authentication and host restrictions remain intact.
• Data exposure, filtering, or token/size limits considered: client metadata is escaped for the header; no additional request payload or credentials are emitted. All test authentication values are non-functional fixtures.

Tool renaming

• I am not renaming tools as part of this PR.

Lint & tests

• script/lint passed in the Codespace.
• script/test passed, including the full race-enabled suite.

Offline compiled-binary probes exercised actual MCP calls and outgoing GraphQL headers for metadata-free builds, malformed metadata, release versions, explicit revisions and embedded VCS metadata. Fallback warnings stayed on stderr; authentication and feature headers were preserved. The tagged live-service E2E suite, full container build and production rollout were not run.

Docs

• Not needed
• Updated README and installation guidance. Tool documentation generation is unnecessary because schemas and toolsets are unchanged.

[Copilot]

Copilot review overview

🟡 Changes recommended

Client metadata can invalidate HTTP headers, and default Docker builds can be incorrectly marked dirty.

Get a fresh assessment by requesting another Copilot review.

Review effort: Balanced
Findings: 1 · 1

Open (2)

• Sanitize client metadata before adding it to the User-Agent header · New
• Avoid marking explicit commit revisions as dirty · New

What changed in this PR

Adds versioned, request-scoped user agents for STDIO GitHub API requests and resolves source-build versions from VCS metadata.

Changes:

• Adds request-scoped user-agent transport handling.
• Resolves release and source revision identifiers.
• Adds protocol, transport, and version tests plus documentation.

File	Description
README.md	Documents source builds and user agents.
pkg/​http/​transport/​user_agent.go	Adds request-scoped user-agent overrides.
pkg/​http/​transport/​user_agent_test.go	Tests concurrent override isolation.
internal/​ghmcp/​server.go	Propagates MCP client identity to API requests.
internal/​ghmcp/​server_test.go	Adds wire-level protocol coverage.
docs/​installation-guides/​README.md	Corrects the package build command.
cmd/​github-mcp-server/​version.go	Resolves and validates build versions.
cmd/​github-mcp-server/​version_test.go	Tests version resolution sources.
cmd/​github-mcp-server/​main.go	Applies resolved versions to STDIO startup.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[jidicula]

Addressed both review findings in 56d11f5.

• Client name/version metadata is escaped before it becomes an HTTP comment. Wire regressions exercise malformed metadata across the supported MCP request paths, retaining authentication, feature headers and request isolation.
• Explicit linked revisions no longer inherit an unrelated embedded dirty bit. Embedded source revisions still retain their real dirty state, releases remain unchanged, and null revision hashes fail explicitly.

Before the implementation fix, the new tests reproduced five header-encoding failures, two explicit-revision/dirty-state failures and eight null-revision failures. After the fix, the complete repository race suite passed. A fresh targeted race run and the pinned analyser also passed after the unrelated formatter-only change had been removed.

GOTOOLCHAIN=go1.25.12 script/lint
script/test
go test -race -count=1 -timeout 5m ./cmd/github-mcp-server ./internal/ghmcp ./pkg/http/transport
bin/golangci-lint run

Validation selected the Go 1.25.12 toolchain root and executable path together, matching the repository's lint setup rather than mixing the image's Go root with a different compiler.

Actual compiled STDIO executables successfully sent list_issues requests to a loopback fixture for modified-source, explicit-revision and release builds. The clean post-commit binary emitted:

github-mcp-server/vcs-56d11f547d37a4c8b52a6a8021d0ca59451dd35a (binary-probe/1.0.0)

Its embedded source revision matches the published commit and reports vcs.modified=false. Authentication values in these probes are non-functional fixtures. No live-service E2E suite, new full container build or deployment was run.

[Copilot]

Copilot review overview

🟢 Approval recommended

The implementation preserves transport isolation and existing headers with comprehensive protocol and version-resolution coverage.

Review effort: Balanced
Findings: None

Resolved since last review (2)

• Sanitize client metadata before adding it to the User-Agent header
• Avoid marking explicit commit revisions as dirty

[SamMorrowDrums]

The user-agent part of this looks good to me. Resolving ClientInfo() per request and passing it through the request context is the right approach for 2026-07-28, where initialize/server/discover are optional and requests have to stand alone. It still works for legacy sessions, it doesn't mutate the shared transport, and the remote server keeps its default behaviour.

One thing needs changing before this merges: resolveServerVersion now makes stdio fail to start when there's no version metadata. On main, version defaults to the literal "version" and gets passed straight through, so a server with no version metadata has always started. I confirmed that a go build -buildvcs=false build now exits with server build has no release or revision. The same would happen with source tarballs or vendored copies that have no .git, and with Docker builds where .git isn't in the build context (git rev-parse HEAD returns nothing and VERSION defaults to dev). Stopping startup over what is only a header label is a regression.

Could you:

• Keep the precedence: release version → explicit main.commit → embedded VCS revision (vcs-<sha>[-dirty]). That part is a nice improvement.
• Fall back instead of erroring: if nothing resolves, use the previous placeholder (or dev), optionally log a warning, and don't return an error.
• Treat malformed values the same way: a short or invalid SHA should fall back or pass through as-is, not block startup.
• Update the README: remove the "STDIO startup reports an error…" wording.

The user-agent fix doesn't depend on the version-resolution work, so splitting that into its own PR would also be fine if that's easier.

[jidicula]

@SamMorrowDrums, addressed the startup regression from #3323 (review). Version resolution now skips missing or malformed candidates while preserving release -> explicit commit -> embedded VCS -> installed module precedence. If none is usable, STDIO starts with dev and a stderr warning; stdout remains reserved for MCP. The README now documents that fallback, and the request-scoped user-agent implementation is unchanged.

Added precedence and fallback regressions. The full race-enabled suite and lint passed in the Codespace, and offline probes of the compiled executable confirmed successful MCP/GraphQL requests for -buildvcs=false, short/invalid revisions, releases and source builds, with authentication and feature headers preserved.

[Copilot]

Copilot review overview

🟢 Approval recommended

The implementation addresses the stated behavior with comprehensive regression coverage and no unresolved correctness issues.

Review effort: Balanced
Findings: None

[SamMorrowDrums]

Thanks for the changes!