Skip to content

💫 Toolkit to help you get started with SDD or any other process!

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

Manfred Riem8f8d4d2406cf
diff --git a/src/specify_cli/artifacts/_mcp.py b/src/specify_cli/artifacts/_mcp.py
new file mode 100644
index 000000000..1a835def0
--- /dev/null
+++ b/src/specify_cli/artifacts/_mcp.py
@@ -0,0 +1,92 @@
+"""MCP registration and inventory for the ``specify artifact`` hierarchy."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Literal
+
+from mcp.server import MCPServer
+
+from ._operation_list import ARTIFACT_LIST_OPERATION
+from .mcp_list import register as register_list
+
+ArtifactOperationId = Literal["artifact.list", "artifact.info", "artifact.lookup"]
+ArtifactCliPath = Literal[
+ "specify artifact list",
+ "specify artifact info",
+ "specify artifact lookup",
+]
+ArtifactToolName = Literal[
+ "specify_artifact_list",
+ "specify_artifact_info",
+ "specify_artifact_lookup",
+]
+ArtifactDisposition = Literal["available", "unavailable"]
+
+
+@dataclass(frozen=True)
+class ArtifactToolInventory:
+ """One authoritative MCP disposition for an artifact CLI leaf."""
+
+ operation_id: ArtifactOperationId
+ cli_path: ArtifactCliPath
+ mcp_tool_name: ArtifactToolName
+ contract_version: str | None
+ disposition: ArtifactDisposition
+ disposition_reason: str | None
+ capabilities: frozenset[Literal["local-read"]]
+ network_access: Literal["none"]
+
+
+ARTIFACT_TOOLS = (
+ ArtifactToolInventory(
+ operation_id=ARTIFACT_LIST_OPERATION.operation_id,
+ cli_path="specify artifact list",
+ mcp_tool_name="specify_artifact_list",
+ contract_version=ARTIFACT_LIST_OPERATION.contract_version,
+ disposition="available",
+ disposition_reason=None,
+ capabilities=ARTIFACT_LIST_OPERATION.capabilities,
+ network_access=ARTIFACT_LIST_OPERATION.network_access,
+ ),
+ ArtifactToolInventory(
+ operation_id="artifact.info",
+ cli_path="specify artifact info",
+ mcp_tool_name="specify_artifact_info",
+ contract_version=None,
+ disposition="unavailable",
+ disposition_reason=(
+ "The artifact.info CLI leaf does not yet have a shared typed operation."
+ ),
+ capabilities=frozenset({"local-read"}),
+ network_access="none",
+ ),
+ ArtifactToolInventory(
+ operation_id="artifact.lookup",
+ cli_path="specify artifact lookup",
+ mcp_tool_name="specify_artifact_lookup",
+ contract_version=None,
+ disposition="unavailable",
+ disposition_reason=(
+ "The artifact.lookup CLI leaf does not yet have a shared typed operation."
+ ),
+ capabilities=frozenset({"local-read"}),
+ network_access="none",
+ ),
+)
+
+
+def register(server: MCPServer, *, launch_directory: Path) -> None:
+ """Register every available artifact tool from the explicit inventory."""
+ available = {
+ item.operation_id: item
+ for item in ARTIFACT_TOOLS
+ if item.disposition == "available"
+ }
+ list_tool = available[ARTIFACT_LIST_OPERATION.operation_id]
+ register_list(
+ server,
+ launch_directory=launch_directory,
+ tool_name=list_tool.mcp_tool_name,
+ )
diff --git a/src/specify_cli/artifacts/_operation_list.py b/src/specify_cli/artifacts/_operation_list.py
index 55cf4beb5..d699fc365 100644
--- a/src/specify_cli/artifacts/_operation_list.py
+++ b/src/specify_cli/artifacts/_operation_list.py
@@ -73,6 +73,8 @@ class ArtifactListHookRow(TypedDict):
ArtifactListItem = ArtifactListRow | ArtifactListHookRow
+ARTIFACT_LIST_MAX_LIMIT = 1000
+ARTIFACT_LIST_CURSOR_MAX_LENGTH = 20
@dataclass(frozen=True)
@@ -80,6 +82,8 @@ class ArtifactListRequest:
"""Explicit project context for the ``artifact.list`` operation."""
project_directory: Path
+ limit: int | None = None
+ cursor: str | None = None
@dataclass(frozen=True)
@@ -87,6 +91,8 @@ class ArtifactListResult:
"""Transport-neutral artifact inventory."""
rows: tuple[ArtifactListItem, ...]
+ next_cursor: str | None = None
+ truncated: bool = False
class ArtifactListError(ArtifactError):
@@ -111,6 +117,17 @@ class ArtifactListError(ArtifactError):
super().__init__(message)
+class ArtifactListProjectDirectoryError(ArtifactListError):
+ """The supplied project directory is not an absolute path."""
+
+ def __init__(self, project_directory: Path) -> None:
+ super().__init__(
+ code="invalid_project_directory",
+ message="project_directory must be an absolute path",
+ details={"project_directory": str(project_directory)},
+ )
+
+
class ArtifactListProjectError(ArtifactListError):
"""The supplied directory is not a Spec Kit project root."""
@@ -133,12 +150,33 @@ class ArtifactListResolutionError(ArtifactListError):
)
+class ArtifactListPaginationError(ArtifactListError):
+ """The requested artifact page is invalid."""
+
+ def __init__(self, *, field: Literal["limit", "cursor"], value: object) -> None:
+ if field == "limit":
+ message = (
+ f"artifact list limit must be between 1 and {ARTIFACT_LIST_MAX_LIMIT}"
+ )
+ else:
+ message = "artifact list cursor must be a canonical decimal offset"
+ super().__init__(
+ code="invalid_pagination",
+ message=message,
+ details={
+ "field": field,
+ "value": value,
+ "max_limit": ARTIFACT_LIST_MAX_LIMIT,
+ },
+ )
+
+
@dataclass(frozen=True)
class ArtifactListOperationDescriptor:
"""Stable metadata shared by delivery adapters for ``artifact.list``."""
operation_id: Literal["artifact.list"]
- contract_version: Literal["1"]
+ contract_version: Literal["2"]
request_type: type[ArtifactListRequest]
result_type: type[ArtifactListResult]
warning_types: tuple[type[object], ...]
@@ -149,21 +187,52 @@ class ArtifactListOperationDescriptor:
ARTIFACT_LIST_OPERATION = ArtifactListOperationDescriptor(
operation_id="artifact.list",
- contract_version="1",
+ contract_version="2",
request_type=ArtifactListRequest,
result_type=ArtifactListResult,
warning_types=(),
- error_types=(ArtifactListProjectError, ArtifactListResolutionError),
+ error_types=(
+ ArtifactListProjectDirectoryError,
+ ArtifactListProjectError,
+ ArtifactListResolutionError,
+ ArtifactListPaginationError,
+ ),
capabilities=frozenset({"local-read"}),
network_access="none",
)
+def _pagination_offset(request: ArtifactListRequest) -> int:
+ limit = request.limit
+ if limit is not None and (
+ isinstance(limit, bool)
+ or not isinstance(limit, int)
+ or limit < 1
+ or limit > ARTIFACT_LIST_MAX_LIMIT
+ ):
+ raise ArtifactListPaginationError(field="limit", value=limit)
+
+ cursor = request.cursor
+ if cursor is None:
+ return 0
+ if (
+ not isinstance(cursor, str)
+ or not cursor
+ or len(cursor) > ARTIFACT_LIST_CURSOR_MAX_LENGTH
+ or not cursor.isascii()
+ or not cursor.isdecimal()
+ or (len(cursor) > 1 and cursor.startswith("0"))
+ ):
+ raise ArtifactListPaginationError(field="cursor", value=cursor)
+ return int(cursor)
+
+
def list_artifacts(request: ArtifactListRequest) -> ArtifactListResult:
- """Return the complete typed artifact inventory for an explicit project."""
+ """Return one typed artifact inventory page for an explicit project."""
project_directory = Path(request.project_directory)
if not project_directory.is_absolute():
- raise ArtifactListProjectError(project_directory)
+ raise ArtifactListProjectDirectoryError(project_directory)
+ offset = _pagination_offset(request)
try:
rows = ArtifactCatalog(project_directory).list_artifacts_with_stack()
@@ -172,6 +241,16 @@ def list_artifacts(request: ArtifactListRequest) -> ArtifactListResult:
except (ArtifactResolutionError, OSError, PresetError) as exc:
raise ArtifactListResolutionError(project_directory) from exc
+ all_rows = tuple(cast(ArtifactListItem, row) for row in rows)
+ page_rows = (
+ all_rows[offset:]
+ if request.limit is None
+ else all_rows[offset : offset + request.limit]
+ )
+ page_end = offset + len(page_rows)
+ truncated = page_end < len(all_rows)
return ArtifactListResult(
- rows=tuple(cast(ArtifactListItem, row) for row in rows),
+ rows=page_rows,
+ next_cursor=str(page_end) if truncated else None,
+ truncated=truncated,
)
diff --git a/src/specify_cli/artifacts/mcp_list.py b/src/specify_cli/artifacts/mcp_list.py
new file mode 100644
index 000000000..bb1dd1369
--- /dev/null
+++ b/src/specify_cli/artifacts/mcp_list.py
@@ -0,0 +1,397 @@
+"""MCP adapter for the shared ``artifact.list`` operation."""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Callable
+from pathlib import Path
+from typing import Annotated, Any, Literal
+
+from mcp.server import MCPServer
+from mcp.types import CallToolResult, TextContent, ToolAnnotations
+from pydantic import BaseModel, ConfigDict, Field, ValidationError, model_validator
+
+from ._operation_list import (
+ ARTIFACT_LIST_CURSOR_MAX_LENGTH,
+ ARTIFACT_LIST_MAX_LIMIT,
+ ArtifactListError,
+ ArtifactListRequest,
+ ArtifactListResult,
+ list_artifacts,
+)
+
+logger = logging.getLogger(__name__)
+_DEFAULT_LIMIT = 100
+_MAX_WIRE_RESPONSE_BYTES = 1024 * 1024
+_WIRE_ENVELOPE_RESERVE_BYTES = 1024
+_INVALID_RESULT_MESSAGE = "The artifact list operation returned an invalid result."
+_INTERNAL_ERROR_MESSAGE = "Unable to list Spec Kit artifacts."
+_RESPONSE_TOO_LARGE_MESSAGE = (
+ "The artifact list result exceeds the MCP response-size limit."
+)
+_SDK_LOOKUP_ERROR = (
+ "MCP SDK compatibility error: registered tool lookup is unavailable."
+)
+_TOOL_DESCRIPTION = (
+ "Return one paginated artifact inventory page for a project. "
+ "While truncated is true, pass next_cursor as cursor to retrieve the next page."
+)
+
+ArtifactListLimit = Annotated[
+ int,
+ Field(strict=True, ge=1, le=ARTIFACT_LIST_MAX_LIMIT),
+]
+ArtifactListCursor = Annotated[
+ str,
+ Field(
+ strict=True,
+ max_length=ARTIFACT_LIST_CURSOR_MAX_LENGTH,
+ pattern=r"^(0|[1-9][0-9]*)$",
+ ),
+]
+ArtifactProjectDirectory = Annotated[str, Field(strict=True)]
+
+
+class ArtifactListToolInput(BaseModel):
+ """Typed input accepted by ``specify_artifact_list``."""
+
+ model_config = ConfigDict(extra="forbid")
+
+ project_directory: ArtifactProjectDirectory | None = None
+ limit: ArtifactListLimit = _DEFAULT_LIMIT
+ cursor: ArtifactListCursor | None = None
+
+
+class ArtifactListStackEntryResult(BaseModel):
+ """Composition entry for a named artifact."""
+
+ model_config = ConfigDict(extra="forbid")
+
+ id: str
+ layer: Literal["project", "preset", "extension"] | None
+ sourceId: str | None
+ presetId: str | None
+ presetName: str | None
+ strategy: Literal["replace", "wrap", "prepend", "append"]
+ active: bool
+ hidden: bool
+ manifestPath: str | None
+ lookupId: str | None
+ sourcePath: str | None
+
+
+class ArtifactListHookStackEntryResult(BaseModel):
+ """Composition entry for a hook artifact."""
+
+ model_config = ConfigDict(extra="forbid")
+
+ id: str
+ layer: Literal["preset", "extension"]
+ sourceId: str
+ presetId: str | None
+ presetName: str | None
+ strategy: Literal["additive"]
+ active: bool
+ hidden: bool
+ manifestPath: str
+ lookupId: str
+ sourcePath: None
+ priority: int
+ optional: bool
+
+
+class ArtifactListRowResult(BaseModel):
+ """One named artifact inventory row."""
+
+ model_config = ConfigDict(extra="forbid")
+
+ id: str
+ name: str
+ kind: Literal["command", "template", "script"]
+ description: str
+ stack: list[ArtifactListStackEntryResult]
+
+
+class ArtifactListHookRowResult(BaseModel):
+ """One hook inventory row."""
+
+ model_config = ConfigDict(extra="forbid")
+
+ id: str
+ name: str
+ kind: Literal["hook"]
+ description: str
+ eventName: str
+ targetCommand: str
+ registered: bool
+ stack: list[ArtifactListHookStackEntryResult]
+
+
+ArtifactListItemResult = Annotated[
+ ArtifactListRowResult | ArtifactListHookRowResult,
+ Field(discriminator="kind"),
+]
+
+
+class ArtifactListToolResult(BaseModel):
+ """Typed structured result returned by ``specify_artifact_list``."""
+
+ model_config = ConfigDict(extra="forbid")
+
+ rows: list[ArtifactListItemResult]
+ next_cursor: ArtifactListCursor | None
+ truncated: bool
+
+ @model_validator(mode="after")
+ def validate_continuation(self) -> ArtifactListToolResult:
+ """Require continuation metadata to agree with truncation state."""
+ if self.truncated != (self.next_cursor is not None):
+ raise ValueError("inconsistent artifact list continuation metadata")
+ return self
+
+
+class _InvalidOperationResult(Exception):
+ """The shared operation returned an incomplete or invalid typed result."""
+
+
+ArtifactListCallResult = Annotated[CallToolResult, ArtifactListToolResult]
+ArtifactListTool = Callable[
+ [ArtifactProjectDirectory | None, ArtifactListLimit, ArtifactListCursor | None],
+ CallToolResult,
+]
+
+
+def _tool_error(
+ code: str,
+ message: str,
+ *,
+ details: dict[str, object] | None = None,
+ retryable: bool = False,
+) -> CallToolResult:
+ payload = {
+ "error": {
+ "code": code,
+ "message": message,
+ "details": details or {},
+ "retryable": retryable,
+ }
+ }
+ return CallToolResult(
+ content=[TextContent(type="text", text=f"{code}: {message}")],
+ structuredContent=payload,
+ isError=True,
+ )
+
+
+def _convert_result(result: ArtifactListResult) -> ArtifactListToolResult:
+ try:
+ rows = result.rows
+ except AttributeError as exc:
+ raise _InvalidOperationResult from exc
+
+ try:
+ return ArtifactListToolResult.model_validate(
+ {
+ "rows": list(rows),
+ "next_cursor": result.next_cursor,
+ "truncated": result.truncated,
+ },
+ strict=True,
+ )
+ except (TypeError, ValidationError) as exc:
+ raise _InvalidOperationResult from exc
+
+
+def _build_success_result(result: ArtifactListToolResult) -> CallToolResult:
+ """Build the duplicated structured and compatibility content sent by MCP."""
+ return CallToolResult(
+ content=[
+ TextContent(
+ type="text",
+ text=result.model_dump_json(indent=2),
+ )
+ ],
+ structuredContent=result.model_dump(mode="json"),
+ isError=False,
+ )
+
+
+def _wire_response_size(result: CallToolResult) -> int:
+ """Bound the serialized result plus conservative JSON-RPC envelope space."""
+ result_bytes = len(
+ result.model_dump_json(by_alias=True, exclude_none=True).encode("utf-8")
+ )
+ return result_bytes + _WIRE_ENVELOPE_RESERVE_BYTES
+
+
+def _response_too_large_error(
+ *,
+ max_wire_response_bytes: int,
+ requested_limit: int,
+) -> CallToolResult:
+ return _tool_error(
+ "response_too_large",
+ _RESPONSE_TOO_LARGE_MESSAGE,
+ details={
+ "max_bytes": max_wire_response_bytes,
+ "requested_limit": requested_limit,
+ },
+ retryable=True,
+ )
+
+
+def _bound_tool_result(
+ result: CallToolResult,
+ *,
+ max_wire_response_bytes: int,
+ requested_limit: int,
+) -> CallToolResult:
+ if _wire_response_size(result) <= max_wire_response_bytes:
+ return result
+ return _response_too_large_error(
+ max_wire_response_bytes=max_wire_response_bytes,
+ requested_limit=requested_limit,
+ )
+
+
+def create_artifact_list_tool(
+ *,
+ launch_directory: Path,
+ max_wire_response_bytes: int = _MAX_WIRE_RESPONSE_BYTES,
+) -> ArtifactListTool:
+ """Create a tool bound to the immutable MCP server launch directory."""
+ launch_directory = Path(launch_directory)
+ if not launch_directory.is_absolute():
+ raise ValueError("MCP server launch directory must be absolute")
+ largest_fallback = _response_too_large_error(
+ max_wire_response_bytes=max_wire_response_bytes,
+ requested_limit=ARTIFACT_LIST_MAX_LIMIT,
+ )
+ if _wire_response_size(largest_fallback) > max_wire_response_bytes:
+ raise ValueError(
+ "MCP response-size limit cannot hold the bounded error response"
+ )
+
+ def specify_artifact_list(
+ project_directory: ArtifactProjectDirectory | None = None,
+ limit: ArtifactListLimit = _DEFAULT_LIMIT,
+ cursor: ArtifactListCursor | None = None,
+ ) -> ArtifactListCallResult:
+ """Return one page; follow next_cursor while truncated is true."""
+ tool_input = ArtifactListToolInput.model_validate(
+ {
+ "project_directory": project_directory,
+ "limit": limit,
+ "cursor": cursor,
+ },
+ strict=True,
+ )
+ selected_directory = (
+ launch_directory
+ if tool_input.project_directory is None
+ else Path(tool_input.project_directory)
+ )
+ try:
+ result = _convert_result(
+ list_artifacts(
+ ArtifactListRequest(
+ project_directory=selected_directory,
+ limit=tool_input.limit,
+ cursor=tool_input.cursor,
+ ),
+ )
+ )
+ success = _build_success_result(result)
+ return _bound_tool_result(
+ success,
+ max_wire_response_bytes=max_wire_response_bytes,
+ requested_limit=tool_input.limit,
+ )
+ except ArtifactListError as exc:
+ return _bound_tool_result(
+ _tool_error(
+ exc.code,
+ exc.message,
+ details=exc.details,
+ retryable=exc.retryable,
+ ),
+ max_wire_response_bytes=max_wire_response_bytes,
+ requested_limit=tool_input.limit,
+ )
+ except _InvalidOperationResult:
+ return _bound_tool_result(
+ _tool_error(
+ "invalid_operation_result",
+ _INVALID_RESULT_MESSAGE,
+ ),
+ max_wire_response_bytes=max_wire_response_bytes,
+ requested_limit=tool_input.limit,
+ )
+ except Exception:
+ logger.exception("Unexpected failure in the artifact list MCP adapter.")
+ return _bound_tool_result(
+ _tool_error("internal_error", _INTERNAL_ERROR_MESSAGE),
+ max_wire_response_bytes=max_wire_response_bytes,
+ requested_limit=tool_input.limit,
+ )
+
+ return specify_artifact_list
+
+
+def _lookup_registered_tool(server: MCPServer, tool_name: str) -> Any | None:
+ try:
+ manager = server._tool_manager
+ get_tool = manager.get_tool
+ except AttributeError as exc:
+ raise RuntimeError(_SDK_LOOKUP_ERROR) from exc
+ try:
+ return get_tool(tool_name)
+ except Exception as exc:
+ raise RuntimeError(_SDK_LOOKUP_ERROR) from exc
+
+
+def _configure_closed_arguments(server: MCPServer, tool_name: str) -> None:
+ tool = _lookup_registered_tool(server, tool_name)
+ if tool is None:
+ raise RuntimeError(f"MCP tool registration was not retained: {tool_name}")
+
+ # MCP SDK argument models ignore extras by default even when discovery
+ # advertises a closed typed schema. Field-level strictness is declared on
+ # the callable; this compatibility shim only closes the generated model.
+ try:
+ argument_model = tool.fn_metadata.arg_model
+ argument_model.model_config["extra"] = "forbid"
+ argument_model.model_rebuild(force=True)
+ tool.parameters = argument_model.model_json_schema(by_alias=True)
+ except Exception as exc:
+ raise RuntimeError(
+ f"MCP SDK compatibility error while closing arguments for {tool_name}"
+ ) from exc
+
+
+def register(
+ server: MCPServer,
+ *,
+ launch_directory: Path,
+ tool_name: str = "specify_artifact_list",
+ max_wire_response_bytes: int = _MAX_WIRE_RESPONSE_BYTES,
+) -> None:
+ """Register the first-class artifact-list MCP tool exactly once."""
+ if _lookup_registered_tool(server, tool_name) is not None:
+ raise ValueError(f"MCP tool name collision: {tool_name}")
+
+ server.add_tool(
+ create_artifact_list_tool(
+ launch_directory=launch_directory,
+ max_wire_response_bytes=max_wire_response_bytes,
+ ),
+ name=tool_name,
+ description=_TOOL_DESCRIPTION,
+ annotations=ToolAnnotations(
+ readOnlyHint=True,
+ idempotentHint=True,
+ openWorldHint=False,
+ ),
+ structured_output=True,
+ )
+ _configure_closed_arguments(server, tool_name)
diff --git a/src/specify_cli/mcp_server/server.py b/src/specify_cli/mcp_server/server.py
index 13d1a9e02..c7b5b6dae 100644
--- a/src/specify_cli/mcp_server/server.py
+++ b/src/specify_cli/mcp_server/server.py
@@ -3,10 +3,12 @@
from __future__ import annotations
from collections.abc import Callable
+from pathlib import Path
from mcp.server import MCPServer
from mcp.types import CallToolResult, TextContent
+from ..artifacts._mcp import register as register_artifacts
from ..mcp_version import register as register_version
from .catalog import (
CommandAdapterError,
@@ -37,8 +39,15 @@ def _tool_error(exc: CommandAdapterError) -> CallToolResult:
def create_server(
*,
command_runner: CommandRunner = run_command,
+ launch_directory: Path | None = None,
) -> MCPServer:
- """Create the experimental version-only MCP server."""
+ """Create the experimental local stdio MCP server."""
+ server_launch_directory = (
+ Path.cwd() if launch_directory is None else Path(launch_directory)
+ )
+ if not server_launch_directory.is_absolute():
+ raise ValueError("MCP server launch directory must be absolute")
+
server = MCPServer(
name="specify",
title="Spec Kit CLI",
@@ -79,6 +88,7 @@ def create_server(
return _tool_error(exc)
register_version(server)
+ register_artifacts(server, launch_directory=server_launch_directory)
return server
diff --git a/tests/specify_cli/artifacts/test_mcp_list.py b/tests/specify_cli/artifacts/test_mcp_list.py
new file mode 100644
index 000000000..b46a41168
--- /dev/null
+++ b/tests/specify_cli/artifacts/test_mcp_list.py
@@ -0,0 +1,1120 @@
+"""Tests for the first-class ``specify_artifact_list`` MCP adapter."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+from pathlib import Path
+from unittest.mock import Mock, patch
+
+import anyio
+import pytest
+from mcp import ClientSession
+from mcp.server import MCPServer
+from mcp.server.mcpserver.exceptions import ToolError
+from mcp.shared.memory import create_client_server_memory_streams
+from mcp.types import CallToolResult
+
+from specify_cli.artifacts import _commands, _mcp, _operation_list, mcp_list
+from specify_cli.artifacts._operation_list import (
+ ARTIFACT_LIST_OPERATION,
+ ArtifactListRequest,
+ ArtifactListResolutionError,
+ ArtifactListResult,
+)
+from specify_cli.artifacts.mcp_list import (
+ ArtifactListToolResult,
+ create_artifact_list_tool,
+)
+from specify_cli.mcp_server.server import create_server
+from specify_cli.presets import PresetError
+
+TOOL_NAME = "specify_artifact_list"
+TOOL_DESCRIPTION = (
+ "Return one paginated artifact inventory page for a project. "
+ "While truncated is true, pass next_cursor as cursor to retrieve the next page."
+)
+
+ARTIFACT_ROWS = (
+ {
+ "id": "template:réview",
+ "name": "réview",
+ "kind": "template",
+ "description": "Réview checklist",
+ "stack": [
+ {
+ "id": "template:réview",
+ "layer": "extension",
+ "sourceId": "quality",
+ "presetId": None,
+ "presetName": None,
+ "strategy": "append",
+ "active": True,
+ "hidden": False,
+ "manifestPath": ".specify/extensions/quality/extension.yml",
+ "lookupId": "extension:quality:template:réview",
+ "sourcePath": (
+ ".specify/extensions/quality/templates/réview-checklist.md"
+ ),
+ }
+ ],
+ },
+ {
+ "id": "hook:before_plan:quality",
+ "name": "quality",
+ "kind": "hook",
+ "description": "Validate quality",
+ "eventName": "before_plan",
+ "targetCommand": "speckit.plan",
+ "registered": True,
+ "stack": [
+ {
+ "id": "hook:before_plan:quality",
+ "layer": "extension",
+ "sourceId": "quality",
+ "presetId": None,
+ "presetName": None,
+ "strategy": "additive",
+ "active": True,
+ "hidden": False,
+ "manifestPath": ".specify/extensions/quality/extension.yml",
+ "lookupId": "extension:quality:hook:before_plan:quality",
+ "sourcePath": None,
+ "priority": 10,
+ "optional": False,
+ }
+ ],
+ },
+)
+
+ARTIFACT_PAYLOAD = {
+ "rows": list(ARTIFACT_ROWS),
+ "next_cursor": None,
+ "truncated": False,
+}
+
+EXPECTED_OUTPUT_SCHEMA = {
+ "$defs": {
+ "ArtifactListHookRowResult": {
+ "additionalProperties": False,
+ "description": "One hook inventory row.",
+ "properties": {
+ "id": {"title": "Id", "type": "string"},
+ "name": {"title": "Name", "type": "string"},
+ "kind": {"const": "hook", "title": "Kind", "type": "string"},
+ "description": {"title": "Description", "type": "string"},
+ "eventName": {"title": "Eventname", "type": "string"},
+ "targetCommand": {"title": "Targetcommand", "type": "string"},
+ "registered": {"title": "Registered", "type": "boolean"},
+ "stack": {
+ "items": {"$ref": "#/$defs/ArtifactListHookStackEntryResult"},
+ "title": "Stack",
+ "type": "array",
+ },
+ },
+ "required": [
+ "id",
+ "name",
+ "kind",
+ "description",
+ "eventName",
+ "targetCommand",
+ "registered",
+ "stack",
+ ],
+ "title": "ArtifactListHookRowResult",
+ "type": "object",
+ },
+ "ArtifactListHookStackEntryResult": {
+ "additionalProperties": False,
+ "description": "Composition entry for a hook artifact.",
+ "properties": {
+ "id": {"title": "Id", "type": "string"},
+ "layer": {
+ "enum": ["preset", "extension"],
+ "title": "Layer",
+ "type": "string",
+ },
+ "sourceId": {"title": "Sourceid", "type": "string"},
+ "presetId": {
+ "anyOf": [{"type": "string"}, {"type": "null"}],
+ "title": "Presetid",
+ },
+ "presetName": {
+ "anyOf": [{"type": "string"}, {"type": "null"}],
+ "title": "Presetname",
+ },
+ "strategy": {
+ "const": "additive",
+ "title": "Strategy",
+ "type": "string",
+ },
+ "active": {"title": "Active", "type": "boolean"},
+ "hidden": {"title": "Hidden", "type": "boolean"},
+ "manifestPath": {"title": "Manifestpath", "type": "string"},
+ "lookupId": {"title": "Lookupid", "type": "string"},
+ "sourcePath": {"title": "Sourcepath", "type": "null"},
+ "priority": {"title": "Priority", "type": "integer"},
+ "optional": {"title": "Optional", "type": "boolean"},
+ },
+ "required": [
+ "id",
+ "layer",
+ "sourceId",
+ "presetId",
+ "presetName",
+ "strategy",
+ "active",
+ "hidden",
+ "manifestPath",
+ "lookupId",
+ "sourcePath",
+ "priority",
+ "optional",
+ ],
+ "title": "ArtifactListHookStackEntryResult",
+ "type": "object",
+ },
+ "ArtifactListRowResult": {
+ "additionalProperties": False,
+ "description": "One named artifact inventory row.",
+ "properties": {
+ "id": {"title": "Id", "type": "string"},
+ "name": {"title": "Name", "type": "string"},
+ "kind": {
+ "enum": ["command", "template", "script"],
+ "title": "Kind",
+ "type": "string",
+ },
+ "description": {"title": "Description", "type": "string"},
+ "stack": {
+ "items": {"$ref": "#/$defs/ArtifactListStackEntryResult"},
+ "title": "Stack",
+ "type": "array",
+ },
+ },
+ "required": ["id", "name", "kind", "description", "stack"],
+ "title": "ArtifactListRowResult",
+ "type": "object",
+ },
+ "ArtifactListStackEntryResult": {
+ "additionalProperties": False,
+ "description": "Composition entry for a named artifact.",
+ "properties": {
+ "id": {"title": "Id", "type": "string"},
+ "layer": {
+ "anyOf": [
+ {
+ "enum": ["project", "preset", "extension"],
+ "type": "string",
+ },
+ {"type": "null"},
+ ],
+ "title": "Layer",
+ },
+ "sourceId": {
+ "anyOf": [{"type": "string"}, {"type": "null"}],
+ "title": "Sourceid",
+ },
+ "presetId": {
+ "anyOf": [{"type": "string"}, {"type": "null"}],
+ "title": "Presetid",
+ },
+ "presetName": {
+ "anyOf": [{"type": "string"}, {"type": "null"}],
+ "title": "Presetname",
+ },
+ "strategy": {
+ "enum": ["replace", "wrap", "prepend", "append"],
+ "title": "Strategy",
+ "type": "string",
+ },
+ "active": {"title": "Active", "type": "boolean"},
+ "hidden": {"title": "Hidden", "type": "boolean"},
+ "manifestPath": {
+ "anyOf": [{"type": "string"}, {"type": "null"}],
+ "title": "Manifestpath",
+ },
+ "lookupId": {
+ "anyOf": [{"type": "string"}, {"type": "null"}],
+ "title": "Lookupid",
+ },
+ "sourcePath": {
+ "anyOf": [{"type": "string"}, {"type": "null"}],
+ "title": "Sourcepath",
+ },
+ },
+ "required": [
+ "id",
+ "layer",
+ "sourceId",
+ "presetId",
+ "presetName",
+ "strategy",
+ "active",
+ "hidden",
+ "manifestPath",
+ "lookupId",
+ "sourcePath",
+ ],
+ "title": "ArtifactListStackEntryResult",
+ "type": "object",
+ },
+ },
+ "additionalProperties": False,
+ "description": "Typed structured result returned by ``specify_artifact_list``.",
+ "properties": {
+ "rows": {
+ "items": {
+ "discriminator": {
+ "mapping": {
+ "command": "#/$defs/ArtifactListRowResult",
+ "hook": "#/$defs/ArtifactListHookRowResult",
+ "script": "#/$defs/ArtifactListRowResult",
+ "template": "#/$defs/ArtifactListRowResult",
+ },
+ "propertyName": "kind",
+ },
+ "oneOf": [
+ {"$ref": "#/$defs/ArtifactListRowResult"},
+ {"$ref": "#/$defs/ArtifactListHookRowResult"},
+ ],
+ },
+ "title": "Rows",
+ "type": "array",
+ },
+ "next_cursor": {
+ "anyOf": [
+ {
+ "maxLength": 20,
+ "pattern": "^(0|[1-9][0-9]*)$",
+ "type": "string",
+ },
+ {"type": "null"},
+ ],
+ "title": "Next Cursor",
+ },
+ "truncated": {
+ "title": "Truncated",
+ "type": "boolean",
+ },
+ },
+ "required": ["rows", "next_cursor", "truncated"],
+ "title": "ArtifactListToolResult",
+ "type": "object",
+}
+
+
+def _run(coro):
+ return asyncio.run(coro)
+
+
+def _expected_error(
+ code: str,
+ message: str,
+ *,
+ details: dict[str, object] | None = None,
+ retryable: bool = False,
+) -> dict[str, object]:
+ return {
+ "error": {
+ "code": code,
+ "message": message,
+ "details": details or {},
+ "retryable": retryable,
+ }
+ }
+
+
+def test_artifact_list_dispatches_directly_to_shared_operation(
+ spec_kit_project: Path,
+):
+ command_runner = Mock(side_effect=AssertionError("subprocess executor reached"))
+
+ with (
+ patch(
+ "specify_cli.artifacts.mcp_list.list_artifacts",
+ return_value=ArtifactListResult(rows=ARTIFACT_ROWS),
+ ) as operation,
+ patch(
+ "specify_cli.mcp_server.executor._run_cli_process",
+ side_effect=AssertionError("subprocess executor reached"),
+ ) as run_cli_process,
+ patch(
+ "specify_cli.artifacts.command_list.artifact_list",
+ side_effect=AssertionError("CLI adapter reached"),
+ ) as cli_adapter,
+ ):
+ server = create_server(
+ command_runner=command_runner,
+ launch_directory=spec_kit_project,
+ )
+ result = _run(server.call_tool(TOOL_NAME, {}))
+
+ assert result.structured_content == ARTIFACT_PAYLOAD
+ request = operation.call_args.args[0]
+ assert request == ArtifactListRequest(
+ project_directory=spec_kit_project,
+ limit=100,
+ cursor=None,
+ )
+ command_runner.assert_not_called()
+ run_cli_process.assert_not_called()
+ cli_adapter.assert_not_called()
+
+
+def test_artifact_list_preserves_complete_typed_rows_unicode_and_order(
+ spec_kit_project: Path,
+):
+ tool = create_artifact_list_tool(launch_directory=spec_kit_project)
+ with patch(
+ "specify_cli.artifacts.mcp_list.list_artifacts",
+ return_value=ArtifactListResult(rows=ARTIFACT_ROWS),
+ ):
+ result = tool()
+
+ assert result.is_error is False
+ assert result.structured_content == ARTIFACT_PAYLOAD
+ assert json.loads(result.content[0].text) == ARTIFACT_PAYLOAD
+ typed_result = ArtifactListToolResult.model_validate(
+ result.structured_content,
+ strict=True,
+ )
+ assert [row.id for row in typed_result.rows] == [
+ "template:réview",
+ "hook:before_plan:quality",
+ ]
+ assert typed_result.rows[0].stack[0].sourcePath.endswith("réview-checklist.md")
+ assert typed_result.rows[1].stack[0].sourcePath is None
+
+
+def test_artifact_list_callable_declares_call_tool_result_contract(
+ spec_kit_project: Path,
+):
+ tool = create_artifact_list_tool(launch_directory=spec_kit_project)
+
+ assert tool.__annotations__["return"] == "ArtifactListCallResult"
+ assert mcp_list.ArtifactListCallResult.__origin__ is CallToolResult
+
+
+def test_artifact_list_uses_server_launch_directory_by_default(
+ spec_kit_project: Path,
+ non_project: Path,
+ monkeypatch: pytest.MonkeyPatch,
+):
+ monkeypatch.chdir(spec_kit_project)
+ server = create_server()
+ monkeypatch.chdir(non_project)
+ operation = Mock(return_value=ArtifactListResult(rows=()))
+ with patch("specify_cli.artifacts.mcp_list.list_artifacts", operation):
+ result = _run(server.call_tool(TOOL_NAME, {}))
+
+ assert result.structured_content == {
+ "rows": [],
+ "next_cursor": None,
+ "truncated": False,
+ }
+ assert operation.call_args.args[0] == ArtifactListRequest(
+ project_directory=spec_kit_project,
+ limit=100,
+ cursor=None,
+ )
+
+
+def test_artifact_list_accepts_explicit_absolute_project_directory(
+ spec_kit_project: Path,
+ non_project: Path,
+):
+ operation = Mock(return_value=ArtifactListResult(rows=()))
+ with patch("specify_cli.artifacts.mcp_list.list_artifacts", operation):
+ result = _run(
+ create_server(launch_directory=non_project).call_tool(
+ TOOL_NAME,
+ {"project_directory": str(spec_kit_project)},
+ )
+ )
+
+ assert result.structured_content == {
+ "rows": [],
+ "next_cursor": None,
+ "truncated": False,
+ }
+ assert operation.call_args.args[0] == ArtifactListRequest(
+ project_directory=spec_kit_project,
+ limit=100,
+ cursor=None,
+ )
+
+
+def test_artifact_list_forwards_pagination_and_returns_continuation(
+ spec_kit_project: Path,
+):
+ operation = Mock(
+ return_value=ArtifactListResult(
+ rows=(ARTIFACT_ROWS[1],),
+ next_cursor="7",
+ truncated=True,
+ )
+ )
+ with patch("specify_cli.artifacts.mcp_list.list_artifacts", operation):
+ result = _run(
+ create_server(launch_directory=spec_kit_project).call_tool(
+ TOOL_NAME,
+ {"limit": 2, "cursor": "5"},
+ )
+ )
+
+ assert result.structured_content == {
+ "rows": [ARTIFACT_ROWS[1]],
+ "next_cursor": "7",
+ "truncated": True,
+ }
+ assert operation.call_args.args[0] == ArtifactListRequest(
+ project_directory=spec_kit_project,
+ limit=2,
+ cursor="5",
+ )
+
+
+def test_artifact_list_rejects_oversized_wire_response(
+ spec_kit_project: Path,
+):
+ tool = create_artifact_list_tool(
+ launch_directory=spec_kit_project,
+ max_wire_response_bytes=2048,
+ )
+ with patch(
+ "specify_cli.artifacts.mcp_list.list_artifacts",
+ return_value=ArtifactListResult(rows=ARTIFACT_ROWS),
+ ):
+ result = tool()
+
+ assert result.is_error is True
+ assert result.structured_content == _expected_error(
+ "response_too_large",
+ "The artifact list result exceeds the MCP response-size limit.",
+ details={"max_bytes": 2048, "requested_limit": 100},
+ retryable=True,
+ )
+ assert result.content[0].text == (
+ "response_too_large: "
+ "The artifact list result exceeds the MCP response-size limit."
+ )
+
+
+def test_artifact_list_isolates_sequential_project_contexts(
+ spec_kit_project: Path,
+ non_project: Path,
+):
+ invocation_cwd = Path.cwd()
+
+ def operation(request: ArtifactListRequest) -> ArtifactListResult:
+ return ArtifactListResult(
+ rows=(
+ {
+ **ARTIFACT_ROWS[0],
+ "id": f"template:{request.project_directory.name}",
+ "name": request.project_directory.name,
+ },
+ )
+ )
+
+ with patch("specify_cli.artifacts.mcp_list.list_artifacts", operation):
+ server = create_server(launch_directory=spec_kit_project)
+ first = _run(
+ server.call_tool(
+ TOOL_NAME,
+ {"project_directory": str(spec_kit_project)},
+ )
+ )
+ second = _run(
+ server.call_tool(
+ TOOL_NAME,
+ {"project_directory": str(non_project)},
+ )
+ )
+
+ assert first.structured_content["rows"][0]["name"] == spec_kit_project.name
+ assert second.structured_content["rows"][0]["name"] == non_project.name
+ assert Path.cwd() == invocation_cwd
+
+
+def test_artifact_list_discovery_has_exact_contract(
+ spec_kit_project: Path,
+):
+ tools = _run(create_server(launch_directory=spec_kit_project).list_tools())
+ tool = next(tool for tool in tools if tool.name == TOOL_NAME)
+
+ assert tool.name == TOOL_NAME
+ assert tool.description == TOOL_DESCRIPTION
+ assert tool.input_schema == {
+ "additionalProperties": False,
+ "properties": {
+ "project_directory": {
+ "anyOf": [{"type": "string"}, {"type": "null"}],
+ "default": None,
+ "title": "Project Directory",
+ },
+ "limit": {
+ "default": 100,
+ "maximum": 1000,
+ "minimum": 1,
+ "title": "Limit",
+ "type": "integer",
+ },
+ "cursor": {
+ "anyOf": [
+ {
+ "maxLength": 20,
+ "pattern": "^(0|[1-9][0-9]*)$",
+ "type": "string",
+ },
+ {"type": "null"},
+ ],
+ "default": None,
+ "title": "Cursor",
+ },
+ },
+ "title": "specify_artifact_listArguments",
+ "type": "object",
+ }
+ assert tool.output_schema == EXPECTED_OUTPUT_SCHEMA
+ assert tool.annotations.read_only_hint is True
+ assert tool.annotations.destructive_hint is None
+ assert tool.annotations.idempotent_hint is True
+ assert tool.annotations.open_world_hint is False
+
+
+def test_artifact_list_rejects_unknown_arguments_before_dispatch(
+ spec_kit_project: Path,
+):
+ operation = Mock(side_effect=AssertionError("operation reached"))
+ with (
+ patch("specify_cli.artifacts.mcp_list.list_artifacts", operation),
+ pytest.raises(ToolError, match="Extra inputs are not permitted"),
+ ):
+ _run(
+ create_server(launch_directory=spec_kit_project).call_tool(
+ TOOL_NAME,
+ {"unexpected": True},
+ )
+ )
+
+ operation.assert_not_called()
+
+
+def test_artifact_list_rejects_invalid_project_directory_type_before_dispatch(
+ spec_kit_project: Path,
+):
+ operation = Mock(side_effect=AssertionError("operation reached"))
+ with (
+ patch("specify_cli.artifacts.mcp_list.list_artifacts", operation),
+ pytest.raises(ToolError, match="Input should be a valid string"),
+ ):
+ _run(
+ create_server(launch_directory=spec_kit_project).call_tool(
+ TOOL_NAME,
+ {"project_directory": 123},
+ )
+ )
+
+ operation.assert_not_called()
+
+
+ "arguments",
+ [
+ {"limit": 0},
+ {"limit": 1001},
+ {"limit": "2"},
+ {"cursor": "01"},
+ {"cursor": 2},
+ ],
+)
+def test_artifact_list_rejects_invalid_pagination_before_dispatch(
+ spec_kit_project: Path,
+ arguments: dict[str, object],
+):
+ operation = Mock(side_effect=AssertionError("operation reached"))
+ with (
+ patch("specify_cli.artifacts.mcp_list.list_artifacts", operation),
+ pytest.raises(ToolError),
+ ):
+ _run(
+ create_server(launch_directory=spec_kit_project).call_tool(
+ TOOL_NAME,
+ arguments,
+ )
+ )
+
+ operation.assert_not_called()
+
+
+def test_artifact_list_rejects_relative_project_directory(
+ spec_kit_project: Path,
+):
+ result = _run(
+ create_server(launch_directory=spec_kit_project).call_tool(
+ TOOL_NAME,
+ {"project_directory": "relative-project"},
+ )
+ )
+
+ assert result.is_error is True
+ assert result.structured_content == _expected_error(
+ "invalid_project_directory",
+ "project_directory must be an absolute path",
+ details={"project_directory": "relative-project"},
+ )
+
+
+def test_artifact_list_maps_non_project_error(non_project: Path):
+ result = _run(create_server(launch_directory=non_project).call_tool(TOOL_NAME, {}))
+
+ assert result.is_error is True
+ assert result.structured_content == _expected_error(
+ "not_a_spec_kit_project",
+ "not a Spec Kit project: no .specify/ directory found",
+ details={"project_directory": str(non_project)},
+ )
+ assert result.content[0].text == (
+ "not_a_spec_kit_project: not a Spec Kit project: no .specify/ directory found"
+ )
+
+
+def test_artifact_list_maps_corrupt_registry_error(spec_kit_project: Path):
+ registry = spec_kit_project / ".specify" / "extensions" / ".registry"
+ registry.write_text("{invalid", encoding="utf-8")
+
+ result = _run(
+ create_server(launch_directory=spec_kit_project).call_tool(TOOL_NAME, {})
+ )
+
+ assert result.is_error is True
+ assert result.structured_content == _expected_error(
+ "artifact_resolution_failed",
+ "artifact resolution failed",
+ details={"project_directory": str(spec_kit_project)},
+ )
+
+
+ "operation_failure",
+ [
+ OSError("unreadable"),
+ PresetError("broken preset"),
+ ],
+)
+def test_artifact_list_preserves_operation_owned_resolution_mapping(
+ spec_kit_project: Path,
+ monkeypatch: pytest.MonkeyPatch,
+ operation_failure: Exception,
+):
+ catalog = Mock()
+ catalog.list_artifacts_with_stack.side_effect = operation_failure
+ monkeypatch.setattr(
+ _operation_list,
+ "ArtifactCatalog",
+ Mock(return_value=catalog),
+ )
+
+ result = _run(
+ create_server(launch_directory=spec_kit_project).call_tool(TOOL_NAME, {})
+ )
+
+ assert result.is_error is True
+ assert result.structured_content == _expected_error(
+ "artifact_resolution_failed",
+ "artifact resolution failed",
+ details={"project_directory": str(spec_kit_project)},
+ )
+
+
+ "operation_result",
+ [
+ None,
+ ArtifactListResult(rows=None),
+ ArtifactListResult(
+ rows=(
+ {
+ "id": "template:incomplete",
+ "name": "incomplete",
+ "kind": "template",
+ "description": "Missing stack",
+ },
+ )
+ ),
+ ArtifactListResult(
+ rows=(
+ {
+ **ARTIFACT_ROWS[0],
+ "unexpected": True,
+ },
+ )
+ ),
+ ArtifactListResult(rows=(), next_cursor=1, truncated=True),
+ ArtifactListResult(rows=(), next_cursor=None, truncated=True),
+ ArtifactListResult(rows=(), next_cursor="1", truncated=False),
+ ],
+)
+def test_artifact_list_rejects_invalid_operation_results(
+ spec_kit_project: Path,
+ operation_result: object,
+):
+ with patch(
+ "specify_cli.artifacts.mcp_list.list_artifacts",
+ return_value=operation_result,
+ ):
+ result = _run(
+ create_server(launch_directory=spec_kit_project).call_tool(TOOL_NAME, {})
+ )
+
+ assert result.is_error is True
+ assert result.structured_content == _expected_error(
+ "invalid_operation_result",
+ "The artifact list operation returned an invalid result.",
+ )
+
+
+def test_artifact_list_sanitizes_and_logs_unexpected_failure(
+ spec_kit_project: Path,
+ caplog: pytest.LogCaptureFixture,
+):
+ unsafe = "SECRET_TOKEN=do-not-print /Users/example/private/project"
+ with (
+ patch(
+ "specify_cli.artifacts.mcp_list.list_artifacts",
+ side_effect=RuntimeError(unsafe),
+ ),
+ caplog.at_level(logging.ERROR, logger="specify_cli.artifacts.mcp_list"),
+ ):
+ result = _run(
+ create_server(launch_directory=spec_kit_project).call_tool(TOOL_NAME, {})
+ )
+
+ assert result.is_error is True
+ assert result.structured_content == _expected_error(
+ "internal_error",
+ "Unable to list Spec Kit artifacts.",
+ )
+ rendered = result.model_dump_json(by_alias=True)
+ assert unsafe not in rendered
+ assert "RuntimeError" not in rendered
+ assert "Traceback" not in rendered
+ assert len(caplog.records) == 1
+ assert caplog.records[0].message == (
+ "Unexpected failure in the artifact list MCP adapter."
+ )
+ assert caplog.records[0].exc_info is not None
+
+
+def test_artifact_inventory_matches_cli_leaves_and_operation_contract(
+ spec_kit_project: Path,
+):
+ cli_operation_ids = {
+ f"artifact.{command.name}"
+ for command in _commands.artifact_app.registered_commands
+ }
+ inventory_operation_ids = [item.operation_id for item in _mcp.ARTIFACT_TOOLS]
+ inventory_tool_names = [item.mcp_tool_name for item in _mcp.ARTIFACT_TOOLS]
+ registered_tool_names = {
+ tool.name
+ for tool in _run(create_server(launch_directory=spec_kit_project).list_tools())
+ }
+
+ assert set(inventory_operation_ids) == cli_operation_ids
+ assert len(inventory_operation_ids) == len(set(inventory_operation_ids))
+ assert len(inventory_tool_names) == len(set(inventory_tool_names))
+ assert all(
+ item.cli_path == f"specify {item.operation_id.replace('.', ' ')}"
+ for item in _mcp.ARTIFACT_TOOLS
+ )
+ assert all(
+ item.mcp_tool_name == f"specify_{item.operation_id.replace('.', '_')}"
+ for item in _mcp.ARTIFACT_TOOLS
+ )
+
+ list_tool = next(
+ item
+ for item in _mcp.ARTIFACT_TOOLS
+ if item.operation_id == ARTIFACT_LIST_OPERATION.operation_id
+ )
+ assert list_tool.contract_version == ARTIFACT_LIST_OPERATION.contract_version
+ assert list_tool.disposition == "available"
+ assert list_tool.disposition_reason is None
+ assert list_tool.capabilities == ARTIFACT_LIST_OPERATION.capabilities
+ assert list_tool.network_access == ARTIFACT_LIST_OPERATION.network_access
+ assert list_tool.mcp_tool_name in registered_tool_names
+
+ unavailable = [
+ item for item in _mcp.ARTIFACT_TOOLS if item.disposition == "unavailable"
+ ]
+ assert {item.operation_id for item in unavailable} == {
+ "artifact.info",
+ "artifact.lookup",
+ }
+ assert all(item.contract_version is None for item in unavailable)
+ assert all(item.disposition_reason for item in unavailable)
+ assert all(item.mcp_tool_name not in registered_tool_names for item in unavailable)
+
+
+def test_artifact_registration_adds_available_tool_once_and_rejects_collision(
+ spec_kit_project: Path,
+):
+ server = MCPServer(name="test")
+
+ _mcp.register(server, launch_directory=spec_kit_project)
+
+ available_names = [
+ item.mcp_tool_name
+ for item in _mcp.ARTIFACT_TOOLS
+ if item.disposition == "available"
+ ]
+ assert [tool.name for tool in _run(server.list_tools())] == available_names
+ with pytest.raises(ValueError, match=f"MCP tool name collision: {TOOL_NAME}"):
+ _mcp.register(server, launch_directory=spec_kit_project)
+ assert [tool.name for tool in _run(server.list_tools())] == available_names
+
+
+def test_sdk_tool_lookup_failure_is_descriptive():
+ with pytest.raises(
+ RuntimeError,
+ match="MCP SDK compatibility error: registered tool lookup is unavailable",
+ ):
+ mcp_list._lookup_registered_tool(object(), TOOL_NAME)
+
+
+def test_sdk_tool_lookup_wraps_manager_failure():
+ server = Mock()
+ server._tool_manager.get_tool.side_effect = RuntimeError("SDK changed")
+
+ with pytest.raises(
+ RuntimeError,
+ match="MCP SDK compatibility error: registered tool lookup is unavailable",
+ ):
+ mcp_list._lookup_registered_tool(server, TOOL_NAME)
+
+
+def test_closed_argument_configuration_requires_retained_registration():
+ server = Mock()
+ server._tool_manager.get_tool.return_value = None
+
+ with pytest.raises(
+ RuntimeError,
+ match=f"MCP tool registration was not retained: {TOOL_NAME}",
+ ):
+ mcp_list._configure_closed_arguments(server, TOOL_NAME)
+
+
+def test_closed_argument_configuration_wraps_incompatible_metadata():
+ server = Mock()
+ server._tool_manager.get_tool.return_value = object()
+
+ with pytest.raises(
+ RuntimeError,
+ match=f"MCP SDK compatibility error while closing arguments for {TOOL_NAME}",
+ ):
+ mcp_list._configure_closed_arguments(server, TOOL_NAME)
+
+
+def test_artifact_tool_requires_absolute_server_launch_directory():
+ with pytest.raises(
+ ValueError,
+ match="MCP server launch directory must be absolute",
+ ):
+ create_artifact_list_tool(launch_directory=Path("relative"))
+
+
+def test_artifact_tool_requires_room_for_bounded_error_response(
+ spec_kit_project: Path,
+):
+ with pytest.raises(
+ ValueError,
+ match="MCP response-size limit cannot hold the bounded error response",
+ ):
+ create_artifact_list_tool(
+ launch_directory=spec_kit_project,
+ max_wire_response_bytes=1024,
+ )
+
+
+def test_in_memory_protocol_enforces_near_boundary_wire_size(
+ spec_kit_project: Path,
+):
+ max_wire_response_bytes = 4096
+ within_limit: ArtifactListResult | None = None
+ oversized: ArtifactListResult | None = None
+
+ for description_length in range(max_wire_response_bytes):
+ candidate = ArtifactListResult(
+ rows=(
+ {
+ **ARTIFACT_ROWS[0],
+ "description": "x" * description_length,
+ },
+ )
+ )
+ converted = mcp_list._convert_result(candidate)
+ wire_size = mcp_list._wire_response_size(
+ mcp_list._build_success_result(converted)
+ )
+ if wire_size <= max_wire_response_bytes:
+ within_limit = candidate
+ continue
+ oversized = candidate
+ assert (
+ len(converted.model_dump_json().encode("utf-8")) < max_wire_response_bytes
+ )
+ break
+
+ assert within_limit is not None
+ assert oversized is not None
+
+ async def exercise():
+ server = MCPServer(name="test")
+ mcp_list.register(
+ server,
+ launch_directory=spec_kit_project,
+ max_wire_response_bytes=max_wire_response_bytes,
+ )
+ operation = Mock(side_effect=[within_limit, oversized])
+ with patch("specify_cli.artifacts.mcp_list.list_artifacts", operation):
+ async with (
+ create_client_server_memory_streams() as (
+ client_streams,
+ server_streams,
+ ),
+ anyio.create_task_group() as task_group,
+ ):
+ task_group.start_soon(
+ server._lowlevel_server.run,
+ server_streams[0],
+ server_streams[1],
+ server._lowlevel_server.create_initialization_options(),
+ )
+ async with ClientSession(*client_streams) as session:
+ await session.initialize()
+ success = await session.call_tool(TOOL_NAME, {})
+ failure = await session.call_tool(TOOL_NAME, {})
+ task_group.cancel_scope.cancel()
+ return success, failure
+
+ success, failure = _run(exercise())
+
+ assert success.is_error is False
+ assert mcp_list._wire_response_size(success) <= max_wire_response_bytes
+ assert failure.is_error is True
+ assert failure.structured_content == _expected_error(
+ "response_too_large",
+ "The artifact list result exceeds the MCP response-size limit.",
+ details={
+ "max_bytes": max_wire_response_bytes,
+ "requested_limit": 100,
+ },
+ retryable=True,
+ )
+
+
+def test_in_memory_protocol_bounds_oversized_expected_error(
+ spec_kit_project: Path,
+):
+ max_wire_response_bytes = 4096
+ oversized_path = Path("/") / ("private-" * 1024)
+
+ async def exercise():
+ server = MCPServer(name="test")
+ mcp_list.register(
+ server,
+ launch_directory=spec_kit_project,
+ max_wire_response_bytes=max_wire_response_bytes,
+ )
+ with patch(
+ "specify_cli.artifacts.mcp_list.list_artifacts",
+ side_effect=ArtifactListResolutionError(oversized_path),
+ ):
+ async with (
+ create_client_server_memory_streams() as (
+ client_streams,
+ server_streams,
+ ),
+ anyio.create_task_group() as task_group,
+ ):
+ task_group.start_soon(
+ server._lowlevel_server.run,
+ server_streams[0],
+ server_streams[1],
+ server._lowlevel_server.create_initialization_options(),
+ )
+ async with ClientSession(*client_streams) as session:
+ await session.initialize()
+ failure = await session.call_tool(TOOL_NAME, {})
+ task_group.cancel_scope.cancel()
+ return failure
+
+ failure = _run(exercise())
+
+ assert failure.is_error is True
+ assert failure.structured_content == _expected_error(
+ "response_too_large",
+ "The artifact list result exceeds the MCP response-size limit.",
+ details={
+ "max_bytes": max_wire_response_bytes,
+ "requested_limit": 100,
+ },
+ retryable=True,
+ )
+ assert str(oversized_path) not in failure.model_dump_json(by_alias=True)
+ assert mcp_list._wire_response_size(failure) <= max_wire_response_bytes
+
+
+def test_in_memory_client_preserves_artifact_success_and_failure_wire_shapes(
+ spec_kit_project: Path,
+):
+ async def exercise():
+ server = create_server(launch_directory=spec_kit_project)
+ async with (
+ create_client_server_memory_streams() as (
+ client_streams,
+ server_streams,
+ ),
+ anyio.create_task_group() as task_group,
+ ):
+ task_group.start_soon(
+ server._lowlevel_server.run,
+ server_streams[0],
+ server_streams[1],
+ server._lowlevel_server.create_initialization_options(),
+ )
+ async with ClientSession(*client_streams) as session:
+ await session.initialize()
+ tools = await session.list_tools()
+ with patch(
+ "specify_cli.artifacts.mcp_list.list_artifacts",
+ return_value=ArtifactListResult(rows=ARTIFACT_ROWS),
+ ):
+ success = await session.call_tool(TOOL_NAME, {})
+ with patch(
+ "specify_cli.artifacts.mcp_list.list_artifacts",
+ return_value=None,
+ ):
+ failure = await session.call_tool(TOOL_NAME, {})
+ schema_failure = await session.call_tool(
+ TOOL_NAME,
+ {"unexpected": True},
+ )
+ task_group.cancel_scope.cancel()
+ return tools, success, failure, schema_failure
+
+ tools, success, failure, schema_failure = _run(exercise())
+
+ discovered = next(tool for tool in tools.tools if tool.name == TOOL_NAME)
+ assert discovered.input_schema["additionalProperties"] is False
+ assert success.is_error is False
+ assert success.structured_content == ARTIFACT_PAYLOAD
+ assert failure.is_error is True
+ assert failure.structured_content["error"]["code"] == "invalid_operation_result"
+ assert schema_failure.is_error is True
+ assert schema_failure.structured_content is None
+ assert "Extra inputs are not permitted" in schema_failure.content[0].text
diff --git a/tests/specify_cli/artifacts/test_operation_list.py b/tests/specify_cli/artifacts/test_operation_list.py
index c898a53dc..52fdb9ea2 100644
--- a/tests/specify_cli/artifacts/test_operation_list.py
+++ b/tests/specify_cli/artifacts/test_operation_list.py
@@ -11,7 +11,10 @@ import yaml
from specify_cli import artifacts
from specify_cli.artifacts import ArtifactCatalog, _operation_list
from specify_cli.artifacts._operation_list import (
+ ARTIFACT_LIST_MAX_LIMIT,
ARTIFACT_LIST_OPERATION,
+ ArtifactListPaginationError,
+ ArtifactListProjectDirectoryError,
ArtifactListProjectError,
ArtifactListRequest,
ArtifactListResolutionError,
@@ -24,13 +27,15 @@ from specify_cli.presets import PresetError
def test_artifact_list_operation_descriptor_is_stable():
assert ARTIFACT_LIST_OPERATION.operation_id == "artifact.list"
- assert ARTIFACT_LIST_OPERATION.contract_version == "1"
+ assert ARTIFACT_LIST_OPERATION.contract_version == "2"
assert ARTIFACT_LIST_OPERATION.request_type is ArtifactListRequest
assert ARTIFACT_LIST_OPERATION.result_type is ArtifactListResult
assert ARTIFACT_LIST_OPERATION.warning_types == ()
assert ARTIFACT_LIST_OPERATION.error_types == (
+ ArtifactListProjectDirectoryError,
ArtifactListProjectError,
ArtifactListResolutionError,
+ ArtifactListPaginationError,
)
assert ARTIFACT_LIST_OPERATION.capabilities == frozenset({"local-read"})
assert ARTIFACT_LIST_OPERATION.network_access == "none"
@@ -48,6 +53,8 @@ def test_list_artifacts_returns_complete_typed_inventory(spec_kit_project: Path)
{"id", "name", "kind", "description", "stack"} <= row.keys()
for row in result.rows
)
+ assert result.next_cursor is None
+ assert result.truncated is False
def test_list_artifacts_preserves_empty_inventory(
@@ -76,6 +83,90 @@ def test_list_artifacts_is_stable_across_repeated_calls(spec_kit_project: Path):
assert [row["id"] for row in first.rows] == [row["id"] for row in second.rows]
+def test_list_artifacts_returns_deterministic_pages(
+ spec_kit_project: Path,
+ monkeypatch: pytest.MonkeyPatch,
+):
+ rows = [
+ {
+ "id": f"template:item-{index}",
+ "name": f"item-{index}",
+ "kind": "template",
+ "description": f"Item {index}",
+ "stack": [],
+ }
+ for index in range(5)
+ ]
+ list_with_stack = Mock(return_value=rows)
+ monkeypatch.setattr(
+ _operation_list,
+ "ArtifactCatalog",
+ lambda _project_directory: Mock(list_artifacts_with_stack=list_with_stack),
+ )
+
+ first = list_artifacts(ArtifactListRequest(spec_kit_project, limit=2))
+ second = list_artifacts(
+ ArtifactListRequest(spec_kit_project, limit=2, cursor=first.next_cursor)
+ )
+ final = list_artifacts(
+ ArtifactListRequest(spec_kit_project, limit=2, cursor=second.next_cursor)
+ )
+
+ assert [row["id"] for row in first.rows] == [
+ "template:item-0",
+ "template:item-1",
+ ]
+ assert first.next_cursor == "2"
+ assert first.truncated is True
+ assert [row["id"] for row in second.rows] == [
+ "template:item-2",
+ "template:item-3",
+ ]
+ assert second.next_cursor == "4"
+ assert second.truncated is True
+ assert [row["id"] for row in final.rows] == ["template:item-4"]
+ assert final.next_cursor is None
+ assert final.truncated is False
+
+
[email protected]("limit", [0, ARTIFACT_LIST_MAX_LIMIT + 1, True])
+def test_list_artifacts_rejects_invalid_limit(
+ spec_kit_project: Path,
+ limit: int,
+):
+ with pytest.raises(ArtifactListPaginationError) as exc_info:
+ list_artifacts(ArtifactListRequest(spec_kit_project, limit=limit))
+
+ assert exc_info.value.code == "invalid_pagination"
+ assert exc_info.value.message == (
+ f"artifact list limit must be between 1 and {ARTIFACT_LIST_MAX_LIMIT}"
+ )
+ assert exc_info.value.details == {
+ "field": "limit",
+ "value": limit,
+ "max_limit": ARTIFACT_LIST_MAX_LIMIT,
+ }
+
+
[email protected]("cursor", ["", "01", "-1", "1.5", "é", "1" * 21, 1])
+def test_list_artifacts_rejects_invalid_cursor(
+ spec_kit_project: Path,
+ cursor: object,
+):
+ with pytest.raises(ArtifactListPaginationError) as exc_info:
+ list_artifacts(ArtifactListRequest(spec_kit_project, cursor=cursor))
+
+ assert exc_info.value.code == "invalid_pagination"
+ assert exc_info.value.message == (
+ "artifact list cursor must be a canonical decimal offset"
+ )
+ assert exc_info.value.details == {
+ "field": "cursor",
+ "value": cursor,
+ "max_limit": ARTIFACT_LIST_MAX_LIMIT,
+ }
+
+
def test_list_artifacts_preserves_unicode_source_paths_and_stack(
spec_kit_project: Path,
):
@@ -146,13 +237,11 @@ def test_list_artifacts_uses_explicit_project_without_process_cwd(
def test_list_artifacts_rejects_relative_project_directory():
- with pytest.raises(ArtifactListProjectError) as exc_info:
+ with pytest.raises(ArtifactListProjectDirectoryError) as exc_info:
list_artifacts(ArtifactListRequest(Path("relative-project")))
- assert exc_info.value.code == "not_a_spec_kit_project"
- assert exc_info.value.message == (
- "not a Spec Kit project: no .specify/ directory found"
- )
+ assert exc_info.value.code == "invalid_project_directory"
+ assert exc_info.value.message == "project_directory must be an absolute path"
assert exc_info.value.details == {"project_directory": "relative-project"}
assert exc_info.value.retryable is False
diff --git a/tests/specify_cli/mcp_server/test_server.py b/tests/specify_cli/mcp_server/test_server.py
index ffe61511e..0c1640a54 100644
--- a/tests/specify_cli/mcp_server/test_server.py
+++ b/tests/specify_cli/mcp_server/test_server.py
@@ -23,19 +23,26 @@ def _run(coro):
return asyncio.run(coro)
-def test_tool_discovery_exposes_first_class_and_transitional_tools():
- tools = _run(create_server().list_tools())
+def test_tool_discovery_exposes_first_class_and_transitional_tools(tmp_path):
+ tools = _run(create_server(launch_directory=tmp_path).list_tools())
assert [tool.name for tool in tools] == [
"specify_list_commands",
"specify_describe_command",
"specify_run_command",
"specify_version",
+ "specify_artifact_list",
]
schemas = {tool.name: tool.input_schema for tool in tools}
assert schemas["specify_list_commands"]["properties"] == {}
assert schemas["specify_version"]["properties"] == {}
assert schemas["specify_version"]["additionalProperties"] is False
+ assert schemas["specify_artifact_list"]["additionalProperties"] is False
+ assert set(schemas["specify_artifact_list"]["properties"]) == {
+ "project_directory",
+ "limit",
+ "cursor",
+ }
for name in ("specify_describe_command", "specify_run_command"):
assert schemas[name]["required"] == ["command"]
assert schemas[name]["properties"]["command"]["type"] == "string"
diff --git a/tests/specify_cli/mcp_server/test_stdio.py b/tests/specify_cli/mcp_server/test_stdio.py
index b3ca22f05..3f9df4292 100644
--- a/tests/specify_cli/mcp_server/test_stdio.py
+++ b/tests/specify_cli/mcp_server/test_stdio.py
@@ -11,7 +11,7 @@ _READ_TIMEOUT_SECONDS = 10
_TEST_TIMEOUT_SECONDS = 30
-def test_real_stdio_server_initializes_discovers_and_runs_version():
+def test_real_stdio_server_initializes_discovers_and_calls_first_class_tools():
async def exercise() -> None:
repo_root = Path(__file__).resolve().parents[3]
parameters = StdioServerParameters(
@@ -34,6 +34,11 @@ def test_real_stdio_server_initializes_discovers_and_runs_version():
tools = await session.list_tools()
listed = await session.call_tool("specify_list_commands", {})
version = await session.call_tool("specify_version", {})
+ artifacts = await session.call_tool("specify_artifact_list", {})
+ artifact_failure = await session.call_tool(
+ "specify_artifact_list",
+ {"project_directory": str(repo_root / "tests")},
+ )
ran = await session.call_tool(
"specify_run_command",
{"command": "version"},
@@ -51,6 +56,7 @@ def test_real_stdio_server_initializes_discovers_and_runs_version():
"specify_describe_command",
"specify_run_command",
"specify_version",
+ "specify_artifact_list",
]
assert listed.structured_content["commands"][0]["command"] == "version"
assert set(version.structured_content) == {
@@ -60,6 +66,20 @@ def test_real_stdio_server_initializes_discovers_and_runs_version():
"features",
}
assert version.is_error is False
+ assert artifacts.is_error is False
+ assert isinstance(artifacts.structured_content["rows"], list)
+ assert artifacts.structured_content["rows"]
+ assert artifacts.structured_content["next_cursor"] is None
+ assert artifacts.structured_content["truncated"] is False
+ assert artifact_failure.is_error is True
+ assert artifact_failure.structured_content == {
+ "error": {
+ "code": "not_a_spec_kit_project",
+ "message": "not a Spec Kit project: no .specify/ directory found",
+ "details": {"project_directory": str(repo_root / "tests")},
+ "retryable": False,
+ }
+ }
assert set(ran.structured_content) == {
"cli_version",
"runtime",