docs(mcp): document the first-class version and artifact tools

[NiniGeek]

Description

docs/reference/mcp.md still describes the version-only server from #4822: three generic tools, only version, and "does not expose ... artifacts". The server now also registers first-class tools that the reference page never mentions:

• specify_version (feat(mcp): add first-class version tool #4864), src/specify_cli/mcp_version.py
• specify_artifact_list (feat(mcp): add first-class artifact list tool #4867), src/specify_cli/artifacts/mcp_list.py
• specify_artifact_info (feat(mcp): add artifact info adapter #4885), src/specify_cli/artifacts/mcp_info.py

All three are wired in create_server() (src/specify_cli/mcp_server/server.py).

This PR:

• lists the first-class tools with their inputs (project_directory, limit 1-1000 default 100, cursor, identifier, kind), results, and error codes, including the retryable 1 MiB response_too_large error;
• keeps the generic tools and their version-only scope;
• states that specify artifact lookup is not exposed yet. It is declared unavailable in ARTIFACT_TOOLS and not registered, which tests/specify_cli/artifacts/test_mcp_list.py asserts. refactor(artifact): extract lookup operation #4952 will likely change that, and the page can be updated when the tool lands;
• removes the stale "version-only" wording from docs/reference/overview.md and from the specify mcp docstring that specify mcp --help prints.

Only documentation and one docstring change; no behavior change.

Testing

• specify mcp --help now prints "Run the experimental MCP server over stdio."
• Ran the MCP tests in the repo venv (uv sync --extra test, then pytest tests/specify_cli/test_command_mcp.py tests/specify_cli/test_mcp_version.py tests/specify_cli/artifacts/test_mcp_list.py tests/specify_cli/artifacts/test_mcp_info.py tests/specify_cli/mcp_server): 147 passed
• markdownlint-cli2 on both changed pages: 0 issues
• Tested with a sample project (not applicable)

Each documented value (limits, error codes, the retryable field, lookup's disposition) was checked against the source cited above.

AI Disclosure

• I did not use AI assistance for this contribution
• I did use AI assistance (fill in the disclosure below)

AI disclosure: Claude Code (Claude Opus 5.5) found the drift by comparing the reference page with the code. A Claude Sonnet 5.5 sub-agent then wrote the edits (default settings, minimal-diff instructions) and ran the tests and the linter. Opus checked the documented values against the source, and I reviewed the full diff before the commit. Scope: documentation and one docstring, no code generation. This PR description was written by Claude Code on my behalf.

🤖 Generated with Claude Code

[Copilot]

🟡 Changes recommended

The documented error contracts incorrectly imply that schema-validation failures contain structured error fields.

1 open finding

• Align schema validation failures with documented error contracts · New

What changed in this PR

Updates the MCP documentation to cover existing first-class version and artifact tools without changing server behavior.

Changes:

• Documents tool inputs, results, pagination, and errors.
• Clarifies generic tools’ version-only scope and artifact lookup’s unavailability.
• Removes obsolete version-only wording from the overview and CLI help.

AI review: GitHub Copilot (model: unknown, autonomous), for the requester; documentation, source, and test inspection only.

File	Description
src/​specify_cli/​command_mcp.py	Updates the MCP command’s help docstring.
docs/​reference/​overview.md	Removes the obsolete version-only limitation.
docs/​reference/​mcp.md	Documents first-class tools and distinguishes the generic surface.

🧠 Review effort: Max

---

💡 Configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[NiniGeek]

Review round 1: summary (commit 2da201b)

• Split schema validation failures from operation failures in docs/reference/mcp.md. Unexpected arguments, an out-of-range limit, a malformed cursor, or an unsupported kind are rejected before dispatch as a text-only tool error with no structured content. This matches test_mcp_list.py, test_mcp_info.py and test_mcp_version.py.
• Removed invalid_pagination and invalid_artifact_kind from the documented MCP error codes. The input schema applies the same checks, so the operation never sees those inputs.
• Moved the specify_version result and error contract (error.code, error.message, error.details) into its own section, separate from the generic tools.

markdownlint passes. Documentation only, no behavior change.

AI disclosure: written by Claude Code (model: Claude Opus 5.5, supervised) on behalf of @NiniGeek. The contributor reviewed the diff before the commit; the agent checked each statement against the cited tests and source.

[Copilot]

🟢 Approval recommended

These documentation and help-text changes have no blocking issues; remaining documentation refinements are non-blocking.

0 open findings

1 resolved since last review

• Align schema validation failures with documented error contracts

Previously missed (1)

In code that hasn't changed since last review

Clarify MCP response size budget and envelope overhead

docs/​reference/​mcp.md:80

The 1 MiB budget applies to the serialized MCP tool response plus reserved JSON-RPC envelope space, not just the artifact data. Both adapters include successful results as text and structured content (mcp_list.py:205-224, mcp_info.py:194-213), so artifact data below 1 MiB can already trigger response_too_large. Please clarify what the budget measures; it also applies to operation-error responses.

AI review: GitHub Copilot (model: unknown, autonomous), for the review requester; documentation, source, and test inspection only.

🧠 Review effort: Max

[mnriem]

Thank you!