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

docs/reference/mcp.md

@@ -17,20 +17,69 @@ Kit banner, Rich output, startup messages, warnings, or logs there.
 
 ## Tools
 
-The server exposes three generic tools:
+The server exposes first-class tools with typed inputs and results. All are
+read-only, local-only (no network access), and reject unexpected arguments.
 
 | Tool | Purpose |
 | --- | --- |
-| `specify_list_commands` | List CLI commands currently supported through MCP |
+| `specify_version` | Return the installed CLI version, runtime, system, and feature capabilities. Takes no arguments. |
+| `specify_artifact_list` | Return one paginated page of a project's artifact inventory (`command`, `template`, `script`, `hook`) |
+| `specify_artifact_info` | Return one artifact and its complete composition stack |
+
+The artifact tools take an optional absolute `project_directory`; it defaults
+to the directory the server was launched from.
+
+`specify_artifact_list` also takes `limit` (1-1000, default 100) and `cursor`.
+Its result has `rows`, `next_cursor`, and `truncated`; while `truncated` is
+true, pass `next_cursor` as `cursor` to get the next page.
+
+`specify_artifact_info` takes `identifier` (bare name or `kind:name`) and an
+optional `kind` (`command`, `template`, `script`, or `hook`).
+
+`specify artifact lookup` is not available through MCP: it does not yet have a
+shared typed operation, so no `specify_artifact_lookup` tool is registered.
+
+Three generic tools are also registered, and support only the dotted command
+`version`; every other command name is rejected with an `unavailable_command`
+tool error.
+
+| Tool | Purpose |
+| --- | --- |
+| `specify_list_commands` | List CLI commands supported by the generic tools |
 | `specify_describe_command` | Describe one supported dotted CLI command |
 | `specify_run_command` | Run one supported command through the real Specify CLI |
 
-This first experimental release supports only the dotted command `version`.
-Every other command name is rejected with an `unavailable_command` tool error.
-The server does not expose project discovery, artifacts, mutations,
-installation or update operations, workflows, confirmations, or access tiers.
+The server does not expose mutations, installation or update operations,
+workflows, confirmations, or access tiers.
+
+## Input validation errors
+
+The first-class tools validate arguments against their input schema before
+running. Unexpected arguments, an out-of-range `limit`, a malformed `cursor`,
+or an unsupported `kind` are rejected as a text-only MCP tool error with no
+structured content, so clients cannot read an `error.code` from it.
+
+## Version tool result and errors
+
+`specify_version` returns the result object directly. If the operation fails,
+it returns an MCP tool error whose structured content has `error.code`
+(`invalid_operation_result` or `internal_error`), `error.message`, and
+`error.details`.
+
+## Artifact results and errors
+
+Artifact tools return their result as structured content. Operation failures
+are MCP tool errors whose structured content has `error.code`,
+`error.message`, `error.details`, and `error.retryable`.
+Both artifact tools can return `invalid_project_directory`,
+`not_a_spec_kit_project`, `artifact_resolution_failed`,
+`invalid_operation_result`, and `internal_error`.
+`specify_artifact_info` can also return `invalid_artifact_identifier`,
+`unknown_artifact`, `unknown_hook`, and `ambiguous_artifact`. Results larger
+than 1 MiB return a retryable `response_too_large` error; for the list tool,
+retry with a smaller `limit`.
 
-## Version result and errors
+## Generic tool result and errors
 
 `specify_run_command` invokes the canonical command below in an isolated child
 process using the same Python environment as the running CLI:

docs/reference/overview.md

@@ -11,8 +11,7 @@ The foundational commands for creating and managing Spec Kit projects. Initializ
 ## MCP Server
 
 The experimental `specify mcp` command exposes stable CLI JSON commands to MCP
-clients through a local stdio server. The initial surface is deliberately
-version-only.
+clients through a local stdio server.
 
 [MCP Server reference →](mcp.md)
 

src/specify_cli/command_mcp.py

@@ -6,7 +6,7 @@
 
 
 def mcp() -> None:
-    """Run the experimental version-only MCP server over stdio."""
+    """Run the experimental MCP server over stdio."""
     from .mcp_server import run_stdio_server
 
     run_stdio_server()