MCP Tools Reference | Specwright
Description: AI-native enterprise documentation platform. Living specs, agent-maintained docs, repo-native knowledge.

Skip to content

# MCP Tools Reference ​

Auto-Generated

This page was auto-generated from MCP server tool metadata on 2026-03-04 16:52 UTC. See source script.

The Specwright MCP server exposes tools for coding agents (Claude Code, Cursor, VS Code Copilot) to query and update the spec knowledge base.

## Setup ​

### Claude Code ​

Add to your project's `.mcp.json`:

json

    {
      "mcpServers": {
        "specwright": {
          "command": "uvx",
          "args": ["specwright", "mcp"]
        }
      }
    }

### Cursor / VS Code ​

Add to your MCP configuration with the same command and args.

## Tools (11) ​

### `search` ​

Search the spec knowledge base using hybrid search (vector + BM25). Returns matching sections with repo, path, title, heading, body snippet, status, and relevance score. Use this to find specs related to what you're working on.

Parameters:

Name | Type | Required | Default
--- | --- | --- | ---
`query` | `str` | Yes | —
`repo` | `str | None` | No
`status` | `str | None` | No
`limit` | `int` | No | 10

### `get_spec` ​

Get a full parsed spec document with frontmatter, sections, acceptance criteria, and status. Returns structured data.

Parameters:

Name | Type | Required | Default
--- | --- | --- | ---
`owner` | `str` | Yes | —
`repo` | `str` | Yes | —
`file_path` | `str` | Yes | —

### `get_section` ​

Get a single section from a spec by its ID. Returns the section with content, acceptance criteria, and ticket link.

Parameters:

Name | Type | Required | Default
--- | --- | --- | ---
`owner` | `str` | Yes | —
`repo` | `str` | Yes | —
`file_path` | `str` | Yes | —
`section_id` | `str` | Yes | —

### `get_doc` ​

Get raw markdown content of any document from a repository. Use this when you need the unprocessed markdown.

Parameters:

Name | Type | Required | Default
--- | --- | --- | ---
`owner` | `str` | Yes | —
`repo` | `str` | Yes | —
`file_path` | `str` | Yes | —

### `list_specs` ​

List all spec documents in a repository (using configured doc_paths). Returns metadata (title, status, owner) without full content.

Parameters:

Name | Type | Required | Default
--- | --- | --- | ---
`owner` | `str` | Yes | —
`repo` | `str` | Yes | —

### `list_docs` ​

List all indexed document paths in the knowledge base. Optionally filter by repository (e.g. 'owner/repo').

Parameters:

Name | Type | Required | Default
--- | --- | --- | ---
`repo` | `str | None` | No

### `get_coverage` ​

Get spec coverage metrics for the organization. Returns aggregate coverage summary (total specs, sections, ACs, realization rate, health score) and a time-series trend. Optionally filter by repository or team.

Parameters:

Name | Type | Required | Default
--- | --- | --- | ---
`repo` | `str | None` | No
`team` | `str | None` | No
`days` | `int` | No | 30

### `create_spec` ​

Create a new spec document in a repository from a template. Commits the file directly to the default branch.

Parameters:

Name | Type | Required | Default
--- | --- | --- | ---
`owner` | `str` | Yes | —
`repo` | `str` | Yes | —
`title` | `str` | Yes | —
`doc_type` | `str` | No | 'spec'
`team` | `str` | No | ''
`owner_name` | `str` | No | ''
`tags` | `list[str] | None` | No
`file_name` | `str | None` | No

### `update_section_status` ​

Update the status of a spec section. Modifies the status comment in-place or inserts one if missing, then commits the change.

Parameters:

Name | Type | Required | Default
--- | --- | --- | ---
`owner` | `str` | Yes | —
`repo` | `str` | Yes | —
`file_path` | `str` | Yes | —
`section_id` | `str` | Yes | —
`new_state` | `str` | Yes | —

### `add_realization` ​

Add realization evidence to a spec section's acceptance criterion. Links a PR and code location to an AC checkbox.

Parameters:

Name | Type | Required | Default
--- | --- | --- | ---
`owner` | `str` | Yes | —
`repo` | `str` | Yes | —
`file_path` | `str` | Yes | —
`section_id` | `str` | Yes | —
`ac_text` | `str` | Yes | —
`pr_number` | `int` | Yes | —
`code_file` | `str` | Yes | —
`lines` | `str` | No | ''

### `sync_spec_status` ​

Bulk update a spec: apply multiple status updates and realizations in a single commit. More efficient than individual calls.

Parameters:

Name | Type | Required | Default
--- | --- | --- | ---
`owner` | `str` | Yes | —
`repo` | `str` | Yes | —
`file_path` | `str` | Yes | —
`status_updates` | `list[dict] | None` | No
`realizations` | `list[dict] | None` | No
`commit_message` | `str` | No | ''