feat: add clipboard_version MCP tool for runtime version reporting

[cmeans-claude-dev]

Summary

• Adds a new MCP tool clipboard_version that returns {"name": "mcp-clipboard", "version": "<x.y.z>"} from importlib.metadata via the existing __version__ symbol.
• Hosts that don't expose the standard MCP serverInfo block to the model (notably Claude Desktop on Windows) leave the agent with no reliable way to determine which build is serving the call. CLI flags --version / --check need shell access, which an in-host agent doesn't have. This closes that gap.
• Concrete motivator: the in-progress mcp-clipboard Windows e2e suite couldn't populate mcp_clipboard_version in per-test result entries because no in-session probe was available. With this tool, the suite's pre-flight (§0 step 2) becomes a single tool call on every platform.

What's in

• src/mcp_clipboard/server.py — registers the 7th @mcp.tool with readOnlyHint: True.
• src/mcp_clipboard/instructions/clipboard_version.md — the description shipped in the wheel and shown in tool listings.
• tests/test_server.py — two tests: tool returns the live __version__, and the instruction file ships and loads.
• CHANGELOG.md — entry under ### Added in [Unreleased].

Test plan

• uv run pytest — full local suite (620 passed locally).
• Build the wheel and confirm instructions/clipboard_version.md is included.
• In a Windows MCP host, call clipboard_version and confirm it returns the installed version string.
• Update the e2e suite's pre-flight step 2 to call clipboard_version (separate change, lands after this merges).

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[cmeans]

Need updates to the README

[cmeans-claude-dev]

Updated. Added a clipboard_version row to the Tools table in README.md describing the new tool (returns {"name": "mcp-clipboard", "version": "<x.y.z>"}, framed as a diagnostic for hosts that don't expose serverInfo and for test-harness version recording), and added clipboard_version.md to the instructions tree under the project-layout section. Pushed as 2b0b469. Ready for re-QA.

[cmeans]

QA Round 1 — QA Failed

Reviewed at head 2b0b469. Code itself is small and clean; verification end-to-end is green. One substantive doc-drift finding plus two observations.

What's clean

• src/mcp_clipboard/server.py:622-634 — @mcp.tool registration follows the established pattern (annotations dict with # type: ignore[arg-type], readOnlyHint: True / destructiveHint: False / idempotentHint: True / openWorldHint: False); function signature returns dict[str, str].
• src/mcp_clipboard/instructions/clipboard_version.md — concise, names the fallback 0.0.0+dev behavior matching src/mcp_clipboard/__init__.py:6-8.
• tests/test_server.py:4313-4326 — two tests cover (a) live __version__ round-trip and (b) instruction file ships and loads; not tautological since they verify shape + name + the version sourcing.
• CHANGELOG.md:7-13 — entry under ## [Unreleased] / ### Added, per project convention.
• README.md:90 (tools table) and README.md:397 (tree) both updated.
• pyproject.toml:52 artifacts = ["src/mcp_clipboard/instructions/*.md", ...] glob captures the new file automatically — no packaging change needed.
• Local verification on 2b0b469: uv run pytest -q → 620 passed, 19 deselected, 5 xfailed in 3.75s. The 19 deselected are the @pytest.mark.integration X11 suite (covered by CI's integration-x11 job, which is green). uv run ruff check src/ tests/ and uv run ruff format --check src/ tests/ clean. uv run mypy src/ clean.
• uv build --wheel produces mcp_clipboard-2.6.1-py3-none-any.whl; unzip -l confirms mcp_clipboard/instructions/clipboard_version.md (624 bytes) ships in the wheel — checkbox 2 verified.
• End-to-end MCP call via claude -p --mcp-config ... --allowedTools mcp__clipboard-qa__clipboard_version returned exactly {"name":"mcp-clipboard","version":"2.6.1"} — round-trip matches the documented contract.
• All 11 actual CI checks green (lint, typecheck, test 3.11/3.12/3.13, integration-x11, version-sync, validate-server-json, codecov/patch).

Findings

F1 — substantive — CLAUDE.md tool count drift. CLAUDE.md:49 reads exposing 6 tools: and lines 50–55 enumerate the six existing tools. Adding clipboard_version makes both stale. Per project history this line is religiously updated each time a tool is added (3 → 4 → 5 → 6 across prior PRs). Bump to 7 tools and add a bullet for clipboard_version() describing the diagnostic role. Doc drift is fixed in the same PR cycle on this project.

F2 — observation — instructions/server.md doesn't mention clipboard_version. That file is the model-facing server instruction loaded by FastMCP and walks through when to use each of the six prior tools. The new diagnostic doesn't fit naturally in any existing paragraph, but a brief sentence — e.g. "Use clipboard_version to record or report which build is serving the current MCP session — diagnostic only" — would aid model-side discoverability. The tool's own instruction file already covers this for tool-listing UIs, so this is optional. Confirm intent or add a one-liner.

F3 — observation — clipboard_version is def, while the other six @mcp.tool functions in the file are async def. Functionally equivalent here (FastMCP accepts both, and the body is a synchronous dict return — confirmed working via the live MCP call above). Worth flagging because it's the only sync @mcp.tool in src/mcp_clipboard/server.py and pattern consistency in a 600+ line file has real reader value. Either is defensible; if def is intentional (no I/O), confirm and I'll close this. Otherwise, async def clipboard_version() aligns with the rest of the file at zero cost.

Outside scope (not findings)

• Test plan checkbox 3 (Windows MCP host call) is not exercisable from this Linux QA session; the 2b0b469 Linux MCP call passed but doesn't substitute for the Windows-host motivation behind the PR. Leaving unchecked for Dev/maintainer.
• Test plan checkbox 4 (e2e suite pre-flight wiring) is explicitly a separate PR.

Verdict

QA Failed — fix F1 (substantive). F2 and F3 need either a fix or a "won't-fix" with rationale before Ready for QA Signoff is on the table.

After Dev addresses, no new commit is needed for F1 if CLAUDE.md is the only change touched (small text edit) — but a fresh commit is cleaner since we're already mid-PR. Re-QA on the new head.

[cmeans]

Audit: applying QA Failed per the round 1 review above. One substantive (CLAUDE.md tool-count drift to 7) plus two observations (server.md mention + sync-vs-async on the new tool) await Dev.

[cmeans]

Round 2 — addressing QA round 1 findings

Pushed as e21cbcb.

F1 (substantive) — fixed. CLAUDE.md:49 bumped from "exposing 6 tools" to "exposing 7 tools" and a new bullet for clipboard_version() added underneath, matching the shape of the existing six. Describes the diagnostic role (host-serverInfo gap, test-harness version recording) so the doc tracks the actual surface area. Edit is local to that block.

F2 (observation) — fixed. Added a short paragraph to src/mcp_clipboard/instructions/server.md describing when to call clipboard_version. Wording: "Use clipboard_version to record or report which build of mcp-clipboard is serving the current MCP session. Diagnostic only; useful when the user asks which version is installed, or when a test harness needs to capture the running version into a result entry." Sits at the end of the file alongside the other tool-use notes; the per-tool instruction file in instructions/clipboard_version.md still carries the full description for tool-listing UIs.

F3 (observation) — fixed. Switched clipboard_version from def to async def in src/mcp_clipboard/server.py:634. Pattern now consistent with the other six @mcp.tool entries in the file. Body is still a synchronous dict return so behavior is unchanged; zero overhead. Test updated to await the coroutine and to be marked @pytest.mark.asyncio.

Verification. uv run pytest -q → 620 passed, 19 deselected, 5 xfailed. Lint and type-check still clean. README, CHANGELOG, and tree listing already covered in round 1's R2 commit (2b0b469); no further changes needed there.

Ready for re-QA on e21cbcb.

[cmeans]

QA Round 2 — QA Failed

Reviewed at head e21cbcb. All three Round 1 findings addressed cleanly. One small new nit on the CLAUDE.md bullet introduced in this round.

Round 1 findings — status

R1 finding	Resolution
F1 substantive — CLAUDE.md tool count drift	Fixed at CLAUDE.md:49 (6 → 7) and a new bullet for clipboard_version() at line 56.
F2 observation — instructions/server.md mention	Fixed at instructions/server.md:38-41 with a clear "Diagnostic only; useful when..." paragraph.
F3 observation — sync def vs async def	Fixed at src/mcp_clipboard/server.py:633 (def → async def); test at tests/test_server.py:4313-4315 correctly gained @pytest.mark.asyncio + await. Confirmed against project convention: every async test in tests/test_server.py uses the explicit marker (271/271), so the marker addition is correct even with asyncio_mode = "auto".

Round 2 verification

• uv run pytest -q → 620 passed, 19 deselected, 5 xfailed in 3.85s (same shape as R1; Dev intentionally didn't add tests since the existing two cover both the contract and the instruction-file load path).
• uv run ruff check src/ tests/ clean. uv run ruff format --check src/ tests/ clean. uv run mypy src/ clean.
• Live MCP call (re-run on e21cbcb after the async conversion) returned {"name":"mcp-clipboard","version":"2.6.1"} — async dispatch works end-to-end.
• All 11 actual CI checks green; only QA Gate StatusContext is PENDING (expected — that's the post-approval gate).

Findings

F1-R2 — nit — CLAUDE.md:56 bullet separator inconsistent with siblings. The new bullet reads:

clipboard_version(). Returns the running mcp-clipboard package version…

while lines 50–55 all use — (em-dash + spaces) between signature and description:

clipboard_copy(content) — Writes text to the system clipboard.

Three-character fix: change (). Returns the running… → () — Returns the running… on CLAUDE.md:56. Trivial but the new bullet is the odd one out in a list of seven.

Verdict

QA Failed — single-line nit on CLAUDE.md:56. Re-QA on the new head; expect a quick Round 3.

[cmeans]

Audit: applying QA Failed per Round 2 review above. R1's three findings all resolved; one trivial new nit on CLAUDE.md:56 (em-dash separator to match siblings).

[cmeans]

Round 3 — F1-R2 nit fixed

Pushed as the new head. Changed CLAUDE.md:56 from clipboard_version()`. Returns the running… to clipboard_version()` — Returns the running… so the new bullet uses the same — separator as the other six tool bullets at lines 50-55. Three-character edit; nothing else touched.

Ready for re-QA.

[cmeans]

QA Round 3 — Ready for QA Signoff

Reviewed at head 8e6da6f. Three rounds total — clean PR.

Round 2 finding — status

R2 finding	Resolution
F1-R2 nit — CLAUDE.md:56 separator	Fixed at CLAUDE.md:56 ((). → () —). New bullet now matches the — pattern of all six sibling bullets at lines 50–55. Pure punctuation diff, no other changes.

Round 3 verification (re-run on 8e6da6f in this session)

• uv run pytest -q → 620 passed, 19 deselected, 5 xfailed in 3.88s.
• uv run ruff check src/ tests/ clean. uv run ruff format --check src/ tests/ clean. uv run mypy src/ clean.
• Live MCP call: claude -p ... --allowedTools mcp__clipboard-qa__clipboard_version returned {"name":"mcp-clipboard","version":"2.6.1"} — async dispatch and instruction-loading both working end-to-end.
• All 11 actual CI checks SUCCESS (lint, typecheck, test 3.11/3.12/3.13, integration-x11, version-sync, validate-server-json, on-push label automation, codecov/patch). Only QA Gate StatusContext is PENDING — expected, that's the post-approval gate.

Round-by-round history

Round	Head	Outcome
R1	2b0b469	QA Failed — F1 substantive (CLAUDE.md tool count drift), F2 observation (server.md mention), F3 observation (sync def vs async def).
R2	e21cbcb	QA Failed — all R1 findings resolved; one new nit F1-R2 on CLAUDE.md bullet separator (. vs —).
R3	8e6da6f	Ready for QA Signoff — F1-R2 fixed; zero open findings.

Cross-link reminders for post-merge

• Test plan checkbox 3 (Windows MCP host call) is the maintainer-side gate before QA Approved — Linux QA can't substitute for the Windows host that motivated this PR. The QEMU + Claude Desktop on Windows lever still applies, same as #138's R6.
• Test plan checkbox 4 — e2e suite pre-flight wiring is explicitly a separate PR; track separately.
• This is a ### Added Unreleased entry — when the next release-PR aggregates Unreleased, the Added category will require a minor bump (per semver §6 and v2.6.0 precedent), not a patch.

Awaiting maintainer QA Approved (gated on the Windows host verification per checkbox 3).

[cmeans]

Audit: applying Ready for QA Signoff per Round 3 review above. Three rounds, zero open findings, full re-verification on 8e6da6f. Awaiting maintainer QA Approved gated on the Windows host verification per test plan checkbox 3.

[cmeans]

LGTM