Skip to content

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

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

Adrien Bettini5946689a230d
diff --git a/docs/reference/mcp.md b/docs/reference/mcp.md
index cf709c03a..b5665f9aa 100644
--- a/docs/reference/mcp.md
+++ b/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:
diff --git a/docs/reference/overview.md b/docs/reference/overview.md
index a489de32c..b5635fe89 100644
--- a/docs/reference/overview.md
+++ b/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)
diff --git a/src/specify_cli/command_mcp.py b/src/specify_cli/command_mcp.py
index c80a883f4..abf6f50d1 100644
--- a/src/specify_cli/command_mcp.py
+++ b/src/specify_cli/command_mcp.py
@@ -6,7 +6,7 @@ import typer
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()