xarmian 2d98f2a170 feat(mcp): advertise cmdhelp_version stability tier in handshake (TASK-963) (#340) ...

* feat(mcp): advertise cmdhelp_version stability tier in handshake (TASK-963)

External agents (Cursor, Claude Desktop, the future Pad Cloud remote MCP
in PLAN-943) depend on tool names, argument shapes, and resource URIs
being stable across pad releases. Without an explicit contract, any
future surface change breaks consumers silently.

This commit ships the contract on two complementary surfaces:

- serverCapabilities.experimental.padCmdhelp in the initialize handshake
  — namespaced map carrying {version, tool_surface_stable}, discoverable
  in one round-trip.
- pad://_meta/version static resource — full JSON document with
  {pad_version, cmdhelp_version, tool_surface_stable, mcp_protocol_version}
  for clients that prefer reading a typed payload.

CmdhelpVersion is pinned at "0.1" — the initial cmdhelp-derived surface
shipped in PLAN-942. Bump the major when tool names / arg shapes /
resource URIs change incompatibly.

Tests:
- TestServer_InitializeHandshake extended to assert the experimental
  capability shape on the wire (not just the existence of the field).
- TestBuildMetaPayload_* lock the payload field names + fallback
  behaviour.
- TestRegisterMeta_ResourceRoundTrip drives the resource through the
  real HandleMessage path so a regression in the dispatcher would
  surface as a test failure.

Docs:
- README's MCP section briefly mentions the contract surfaces.
- CLAUDE.md's MCP section gets a stability-contract paragraph + the new
  resource URI.
- Public docs at getpad.dev/mcp/local will need a follow-up PR in the
  pad-web repo (per CONVE-159) — captured at the end of TASK-963.

Parent: PLAN-942.

* fix(mcp): source MCP protocol version from mcp-go LATEST_PROTOCOL_VERSION per Codex review (round 1)

Codex caught: the local MCPProtocolVersion constant was pinned at
"2024-11-05", but mcp-go@v0.50.0 negotiates "2025-11-25" for clients
that request mcp.LATEST_PROTOCOL_VERSION. The meta resource was
therefore reporting a protocol revision newer than what the server
actually speaks, which defeats the field's purpose for feature
detection (e.g. RFC 8707 Resource Indicators land in 2025-11-25).

Drop the local constant and read mcp.LATEST_PROTOCOL_VERSION at
BuildMetaPayload time so the value tracks whatever revision the
linked library will negotiate. The handshake's serverInfo.version
already does this implicitly via NewMCPServer; making the meta
resource follow the same source-of-truth keeps both surfaces in
lockstep across mcp-go upgrades.

Test updated to assert against mcp.LATEST_PROTOCOL_VERSION instead of
the removed constant, plus an "empty-string" guard in case a future
library refactor unsets the constant.

Parent: PLAN-942.

2026-05-01 10:54:01 -04:00

..

pad

feat(mcp): advertise cmdhelp_version stability tier in handshake (TASK-963) (#340)

2026-05-01 10:54:01 -04:00