From 52274c9ba9a5b2c2a858e7894d430c7ca879f77e Mon Sep 17 00:00:00 2001 From: Adrien Bettini Date: Thu, 15 Oct 2026 10:13:27 +0200 Subject: [PATCH 1/2] docs(mcp): document the first-class version and artifact tools docs/reference/mcp.md still described the version-only server from #4822. The server now also registers specify_version (#4864), specify_artifact_list (#4867) and specify_artifact_info (#4885). Document their inputs, results and errors, state that artifact lookup is not exposed yet, and drop the stale "version-only" wording from the overview page and the `specify mcp --help` docstring. Assisted-by: Claude Code (model: Claude Sonnet 5.5, orchestrated by Claude Opus 5.5, supervised) Co-Authored-By: Claude Opus 5.5 --- docs/reference/mcp.md | 54 +++++++++++++++++++++++++++++----- docs/reference/overview.md | 3 +- src/specify_cli/command_mcp.py | 2 +- 3 files changed, 49 insertions(+), 10 deletions(-) diff --git a/docs/reference/mcp.md b/docs/reference/mcp.md index cf709c03a4..0dbfaafdb8 100644 --- a/docs/reference/mcp.md +++ b/docs/reference/mcp.md @@ -17,20 +17,60 @@ 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. + +## Artifact results and errors + +Artifact tools return their result as structured content. Failures are MCP tool +errors with `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_list` can also return `invalid_pagination`. +`specify_artifact_info` can also return `invalid_artifact_kind`, +`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`. + +## Generic version result and errors -## Version result and errors +`specify_version` returns the result object directly; on failure it returns an +`invalid_operation_result` or `internal_error` tool error. The details below +describe the generic tools. `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 a489de32c9..b5635fe89e 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 c80a883f4f..abf6f50d1b 100644 --- a/src/specify_cli/command_mcp.py +++ b/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() From 2da201bdeb395682ee2270d35b8b519d2e4df17b Mon Sep 17 00:00:00 2001 From: Adrien Bettini Date: Thu, 15 Oct 2026 16:07:12 +0200 Subject: [PATCH 2/2] docs(mcp): separate schema validation errors from operation errors Schema validation rejects unexpected arguments, an out-of-range limit, a malformed cursor, or an unsupported kind before the operation runs, as a text-only tool error with no structured content. Document that separately, drop invalid_pagination and invalid_artifact_kind (the schema makes them unreachable through MCP), and give specify_version its own result and error section. Addresses review feedback on #4969. Assisted-by: Claude Code (model: Claude Opus 5.5, supervised) Co-Authored-By: Claude Opus 5.5 --- docs/reference/mcp.md | 35 ++++++++++++++++++++++------------- 1 file changed, 22 insertions(+), 13 deletions(-) diff --git a/docs/reference/mcp.md b/docs/reference/mcp.md index 0dbfaafdb8..b5665f9aa5 100644 --- a/docs/reference/mcp.md +++ b/docs/reference/mcp.md @@ -52,25 +52,34 @@ tool error. 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. Failures are MCP tool -errors with `error.code`, `error.message`, `error.details`, and -`error.retryable`. +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_list` can also return `invalid_pagination`. -`specify_artifact_info` can also return `invalid_artifact_kind`, -`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`. - -## Generic version result and errors +`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`. -`specify_version` returns the result object directly; on failure it returns an -`invalid_operation_result` or `internal_error` tool error. The details below -describe the generic tools. +## 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: