feat(mcp): add first-class artifact list tool

[mnriem]

Summary

• add specify_artifact_list as a first-class typed MCP adapter that dispatches directly to the shared artifact.list operation
• capture immutable server-launch project context while supporting explicit absolute project directories without process-wide cwd changes and returning an actionable invalid_project_directory error for relative paths
• version the revised expected-error contract as artifact.list contract v2
• add operation-owned limit/cursor pagination with explicit next_cursor/truncated metadata and discovery guidance for traversing every page
• declare the SDK-supported Annotated[CallToolResult, ArtifactListToolResult] return contract so runtime typing and the advertised structured output schema remain accurate
• enforce strict field validation and reject unknown arguments before dispatch; necessary MCP SDK internal hooks are guarded with descriptive compatibility failures
• bound every adapter-produced CallToolResult, including expected and internal failures, against the actual duplicated MCP representation plus conservative JSON-RPC envelope space; oversized results use a prevalidated retryable fallback that cannot echo oversized details
• add hierarchy-owned artifact MCP inventory and registration, with artifact.info and artifact.lookup explicitly deferred until they have shared typed operations
• preserve the three transitional generic tools, existing specify_version behavior, and the CLI's complete unpaginated default

Validation

• .venv/bin/python -m pytest tests/specify_cli/artifacts tests/specify_cli/mcp_server tests/specify_cli/test_mcp_version.py tests/specify_cli/test_operation_version.py tests/specify_cli/test_command_version.py -q — 268 passed
• .venv/bin/python -m pytest tests/specify_cli/artifacts/test_mcp_list.py --cov=specify_cli.artifacts.mcp_list --cov-report=term-missing -q — 40 passed; 100.00% adapter statement coverage (156/156)
• .venv/bin/python -m pytest --collect-only -q — 9851 collected, up from the 9800 baseline
• LC_ALL=en_US.UTF-8 .venv/bin/python -m pytest -q — 9832 passed, 19 skipped, 62 warnings
• ruff 0.16.9 check ... — passed for all touched Python files
• ruff 0.16.9 format --check ... — passed for all touched Python files
• git diff --check — passed

Repository branch coverage is not enabled; focused statement coverage for the MCP adapter is 100%.

AI disclosure

This pull request was authored by GitHub Copilot (model: GPT-5.6 Sol, autonomous) on behalf of @mnriem.

[Copilot]

🟡 Changes recommended

Artifact results remain unbounded despite the repository’s explicit MCP pagination and response-size requirements.

1 open finding

• Add pagination and limits to bound artifact and stack results · New

What changed in this PR

Adds a typed, first-class MCP adapter for artifact listing with project-scoped context and explicit registration.

Changes:

• Adds typed artifact list schemas, dispatch, and error mapping.
• Adds hierarchy-owned MCP inventory and registration.
• Adds comprehensive adapter, protocol, and server tests.

File	Description
src/​specify_cli/​artifacts/​mcp_list.py	Implements the artifact-list MCP adapter.
src/​specify_cli/​artifacts/​_mcp.py	Defines artifact MCP inventory and registration.
src/​specify_cli/​mcp_server/​server.py	Captures launch context and registers artifact tools.
tests/​specify_cli/​artifacts/​test_mcp_list.py	Tests contracts, dispatch, errors, and protocol behavior.
tests/​specify_cli/​mcp_server/​test_server.py	Updates tool discovery expectations.
tests/​specify_cli/​mcp_server/​test_stdio.py	Exercises the tool over real stdio.

🧠 Review effort: Balanced

---

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

[mnriem]

Addressed the pagination and response-bounding review in 280bf593fbb522e3d69024528477044b9d27afc7.

• added operation-owned limit/cursor pagination with explicit next_cursor and truncated metadata
• retained complete unpaginated CLI output while defaulting MCP calls to bounded 100-row pages
• added a 1 MiB adapter response budget with retryable response_too_large failures for oversized pages or stack-heavy rows
• added positive continuation and negative invalid-pagination/oversized-output coverage

Validation: 259 focused tests passed; focused operation/adapter coverage is 100% (274/274 statements); collection increased from 9800 to 9842; full suite passed with 9823 passed and 19 skipped; Ruff and git diff --check passed.

This review-round update was generated by GitHub Copilot (model: GPT-5.6 Sol, autonomous) on behalf of @mnriem.

[Copilot]

🟡 Changes recommended

Input coercion and incomplete wire-size accounting undermine the advertised MCP contract.

2 open findings

• Bound actual MCP wire response size · New
• Document paginated artifact discovery and next_cursor handling · New

1 resolved since last review

• Add pagination and limits to bound artifact and stack results

🧠 Review effort: Balanced

[mnriem]

Addressed the second review round in c18ef28824ed1ffd3a0fb3fb72571a4c22fe0906.

• measure and bound the complete duplicated MCP CallToolResult plus conservative JSON-RPC envelope space, rather than only the structured model
• add a near-boundary in-memory protocol test demonstrating rejection when the model fits but the wire result exceeds the limit
• enforce strict validation on the SDK-generated argument model so coercible wrong types are rejected before operation dispatch
• update discovery and callable documentation to describe pagination and following next_cursor while truncated is true

Validation: 262 focused tests passed; focused shared-operation/MCP coverage is 100% (282/282 statements); collection increased from 9800 to 9845; full suite passed with 9826 passed and 19 skipped; Ruff and git diff --check passed.

This review-round update was generated by GitHub Copilot (model: GPT-5.6 Sol, autonomous) on behalf of @mnriem.

[Copilot]

Warning

Copilot couldn't run its full agentic review because it didn't start before the timeout. Make sure your repository has a runner available, or add a copilot-code-review.yml file specifying one with the runs-on attribute. See the docs for more details.

Copilot review overview

7 open findings

• When project_directory is relative, ArtifactListProjectError is raised with the message “not a… · New
• The specify_artifact_list return annotation is incorrect: the function always returns a… · New
• The specify_artifact_list return annotation is incorrect: the function always returns a… · New
• The specify_artifact_list return annotation is incorrect: the function always returns a… · New
• This relies on private/internal MCP SDK attributes (server._tool_manager, tool.fn_metadata,… · New
• This relies on private/internal MCP SDK attributes (server._tool_manager, tool.fn_metadata,… · New
• This relies on private/internal MCP SDK attributes (server._tool_manager, tool.fn_metadata,… · New

2 resolved since last review

• Bound actual MCP wire response size
• Document paginated artifact discovery and next_cursor handling

🧠 Review effort: Lite

[mnriem]

Addressed the third review round in 1fa5ce15c395d5e2a6407fc8346bcac1db0c2584.

• added an actionable invalid_project_directory operation error for relative paths, preserving not_a_spec_kit_project for absolute non-project paths
• corrected the callable contract to the SDK-supported Annotated[CallToolResult, ArtifactListToolResult], accurately typing the runtime result while preserving the structured output schema
• moved strictness to public field annotations and hardened the remaining narrow private SDK compatibility shim with descriptive registration-time failures and dedicated coverage

Validation: 267 focused tests passed; focused shared-operation/MCP coverage is 100% (302/302 statements); collection increased from 9800 to 9850; full suite passed with 9831 passed and 19 skipped; Ruff and git diff --check passed.

This review-round update was generated by GitHub Copilot (model: GPT-5.6 Sol, autonomous) on behalf of @mnriem.

[Copilot]

🟡 Changes recommended

Error responses can exceed the wire-size budget, and the changed expected-error contract retains the old major version.

2 open findings

• Bound oversized expected-error responses · New
• Bump contract version for changed expected error · New

7 resolved since last review

• This relies on private/internal MCP SDK attributes (server._tool_manager, tool.fn_metadata,…
• This relies on private/internal MCP SDK attributes (server._tool_manager, tool.fn_metadata,…
• This relies on private/internal MCP SDK attributes (server._tool_manager, tool.fn_metadata,…
• The specify_artifact_list return annotation is incorrect: the function always returns a…
• The specify_artifact_list return annotation is incorrect: the function always returns a…
• The specify_artifact_list return annotation is incorrect: the function always returns a…
• When project_directory is relative, ArtifactListProjectError is raised with the message “not a…

🧠 Review effort: Balanced

[mnriem]

Addressed review 5447321748 in c1c5aeb2:

• all adapter-produced MCP results now share one final wire-size bound, including expected and sanitized failure results
• oversized failures are replaced by a prevalidated response_too_large fallback that omits the original oversized details
• an in-memory protocol regression proves a huge expected-error path cannot escape through text or structured content and the fallback remains within budget
• the changed expected-error semantics are now declared as artifact.list contract version 2; artifact inventory continues to derive that version from the operation descriptor

Validation: 268 focused artifact/MCP/version tests passed; adapter statement coverage is 100% (156/156); collection is 9,851 versus the 9,800 baseline; the full suite passed with 9,832 passed and 19 skipped; Ruff check/format and git diff --check passed. Repository branch coverage is not enabled.

This comment was generated by GitHub Copilot (model: GPT-5.6 Sol, autonomous) on behalf of @mnriem.

[Copilot]

🟢 Approval recommended

The implementation follows the MCP architecture and includes thorough positive, negative, boundary, and protocol coverage.

0 open findings

2 resolved since last review

• Bound oversized expected-error responses
• Bump contract version for changed expected error

🧠 Review effort: Balanced