Skip to content

MCP tools

This page lists each tool of Speccy’s MCP server. speccy mcp runs the server over stdio as the local user. In hosted mode the same tools are at /mcp, with a personal API token. Hand a spec to a coding agent shows the setup.

Approve a requested waiver under the profile’s waiver policy. Speccy refuses an approval that the policy does not allow to the person. The final approval writes the waiver to the doc’s sidecar, and the finding no longer counts in the verdict. Approve only when the person tells you to approve this waiver.

Input Type Required Meaning
waiver_id string yes the id of the waiver, from request_waiver or list_waivers

Turn the person’s concern about a spec pull request into one precise question for the author, on the section it is about, in the person’s pending review. status posted: the question is in the pending review. status answered: the doc already answers it; the answer gives the quote that does, and nothing is posted unless you call again with force. status unclear: the concern fits more than one section; ask the person which one, and call again with section. Local mode only.

Input Type Required Meaning
concern string yes the person’s concern, in their own words
force boolean post the question although the doc already answers the concern
no_attribution boolean post the question with no hidden marker that names Speccy
section null or array the heading path of the section, when the concern fits more than one
url string yes the URL of the pull request

Stop a batch of pull request reviews: no new pull request starts, and the reviews that run now finish and post.

Input Type Required Meaning
batch string yes the batch ID that review_prs gave

Delete comments of the person’s pending review on a pull request, by the IDs that list_pending gives. Delete only the comments the person named.

Input Type Required Meaning
ids null or array yes the IDs of the comments, from list_pending
url string yes the URL of the pull request

Discard the person’s whole pending review on pull requests: the ones named by URL, each open pull request of a repo, or each pull request of a batch. Name exactly one of urls, repo and batch. Nothing the author can see changes.

Input Type Required Meaning
batch string a batch ID: each pull request the batch posted on
repo string a repo as owner/name: each of its open pull requests
urls null or array the URLs of the pull requests

Get the state of a batch of pull request reviews: for each pull request, waiting, reviewing, posted, skipped with the reason, or failed with the error, and for a posted one the verdict of each spec doc, the count of comments, and the link to the pending review.

Input Type Required Meaning
batch string yes the batch ID that review_prs gave

Get the breakdown of a doc: its epics, its work items, its findings, its coverage of the doc’s trace IDs, the pushed issues, and its revision. stale is true when the doc has a newer version; changed names what the new version changed in each item.

Input Type Required Meaning
bundle string yes the bundle’s slug or ID

Get one bundle: its files, its verdict, and the text of its spec doc. Pass version, a version number, to read the doc as it was at that version, such as the version a work item was pushed from.

Input Type Required Meaning
bundle string yes the bundle’s slug or ID
version integer a version number, to read the doc as it was at that version. Absent is the current version

Get the fix list of a bundle: the findings of its current verdict, MUST first. Each has a message, a suggested fix, the file, line and end_line of its text, and a fix_kind. fix_kind reword means you change the words and no fact. fix_kind answer means the fix needs a fact from the person: the finding has the question to ask them. The answer also gives the state of the review: the version the AI review read, the count of sections changed since, and the trend. A section changed since has no AI result until the next review.

Input Type Required Meaning
bundle string yes the bundle’s slug or ID
level string only findings at this level: MUST, SHOULD, or INFO

Get everything that blocks Build Ready and needs a person, in doc order: material gaps with two options and a suggested pick, blocking threads, and blocking findings.

Input Type Required Meaning
bundle string yes the bundle’s slug or ID

Get a bundle’s links, trace ID coverage, and suggested trace IDs.

Input Type Required Meaning
bundle string yes the bundle’s slug or ID

Get the current verdict of a bundle.

Input Type Required Meaning
bundle string yes the bundle’s slug or ID

Get the slice of the spec one work item builds: its quoted criteria with their heading paths, the agreed build answers for its trace IDs, the linked docs, the external links, and the doc at the version the item was pushed from. ref is one string: the work item’s Speccy URL, its tracker issue URL or key, or bundle/item. newer_version is true when the doc changed after the push: ask the author before you build from the old text.

Input Type Required Meaning
ref string yes the work item’s Speccy URL, its tracker issue URL or key, or bundle/item

Take the build packet of a Build Ready bundle: its spec doc, its assets, the spec doc of each bundle it links to, its trace IDs, the build questions with the answer independent readers agreed on, and a re-entry prompt to build from. Speccy records which version you took.

Input Type Required Meaning
acknowledged boolean take the packet although the bundle is not Build Ready, or its verdict is stale
bundle string yes the bundle’s slug or ID
label string what you call this work: a repo, a branch, or an issue

List the bundles with their verdicts.

It takes no input.

List the comments of the person’s pending review on a pull request: each with its ID, file, line, first words, and whether Speccy wrote it. Call it before delete_pending, and show the list to the person.

Input Type Required Meaning
url string yes the URL of the pull request

List the discussion threads of a bundle.

Input Type Required Meaning
bundle string yes the bundle’s slug or ID

List the waivers of a bundle, newest first: each with its check, section, reason, status, approvals, and for a contradiction the conflict it excuses.

Input Type Required Meaning
bundle string yes the bundle’s slug or ID

Post a message to a thread, or open a thread on a bundle when no thread_id is given.

Input Type Required Meaning
body string yes the message
bundle string with no thread_id: the bundle to open a new thread on, by slug or ID
thread_id string the thread to post to
title string with no thread_id: the title of the new thread

Propose a breakdown of a Build Ready doc: epics, and work items under them. Each work item holds its trace IDs, its acceptance criteria quoted from the doc, the agreed build answers, its target repo, its dependencies and its open questions. A doc that is not Build Ready is refused with its MUST count; acknowledged proposes it anyway. The answer is the draft with its findings: a MUST finding blocks the push. A new proposal replaces a breakdown that has no pushed issue.

Input Type Required Meaning
acknowledged boolean propose it although the doc is not Build Ready. The breakdown stores the verdict
bundle string yes the bundle’s slug or ID

Push the breakdown to a tracker: create the epics and the work items that have no issue yet, with their dependencies and assignees. tracker is linear, jira or github; target is the Linear team, the Jira project URL, or the GitHub repo. A push never edits or closes an issue, and records one handoff with the label breakdown. It is refused while the breakdown has a MUST finding or is stale. Push only when the person tells you to push this breakdown.

Input Type Required Meaning
acknowledged boolean push although the doc is not Build Ready. The handoff stores the verdict
based_on integer yes the revision of the breakdown the person approved
bundle string yes the bundle’s slug or ID
target string yes the Linear team, the Jira project URL, or the GitHub repo as owner/name
tracker string yes linear, jira or github

Report what you learned about the doc while you built from a build packet. kind blocked means you cannot build the section without an answer, and it opens a blocking thread. kind note means you built something and the doc was unclear. Name the section or the trace ID, so the question lands on that text.

Input Type Required Meaning
handoff string yes the handoff ID from the build packet
kind string yes blocked or note
section null or array the heading path of the section the report is about
text string yes what you need, in your own words
trace_id string a trace ID the report is about, such as REQ-012

Ask for a waiver of one MUST or SHOULD finding of a bundle: an approved exception for its check in its section, with a reason. A waiver of coherence.contradiction excuses only the one conflict of the finding. With upstream_change, the answer to a coherence.contradiction finding is that the linked doc must change: after approval the conflict waits on that doc and does not block. With send_back, the answer to a coherence.downstream-request finding is that the downstream doc must change: after approval the conflict blocks that doc again. The reason must come from the person: ask them why the check does not apply here, and pass their words. Never write a reason yourself. The reason needs at least 20 characters. A coverage gap takes no waiver. The answer is the waiver, with the approvals its policy needs. In local mode the waiver is approved at once, because the one person is the approver; an upstream request or a send-back still waits.

Input Type Required Meaning
bundle string yes the bundle’s slug or ID
finding_id string yes the id of the finding, from get_findings
reason string yes why the check does not apply here, in the person’s own words. At least 20 characters
send_back boolean answer a coherence.downstream-request finding with: the downstream doc must change. Only when the person says that this doc is right
upstream_change boolean answer a coherence.contradiction finding with: the linked doc must change. Only when the person says that the other doc is wrong

Run a review of a saved bundle and wait for the verdict. The model stages can take minutes.

Input Type Required Meaning
bundle string yes the bundle’s slug or ID
stages null or array the model stages to run: rubric, grounding, divergence, coherence. Absent means all.

Review markdown files that are not saved: a spec doc with a type in its frontmatter, and its assets. No bundle changes; the server keeps the result for its report for 90 days.

Input Type Required Meaning
files null or array yes the spec doc and its assets
main_doc string the spec doc of a single-file bundle, when its frontmatter has no type
profile string the profile for a spec doc with no type, such as prd or sdd
slug string the bundle’s slug, so links to and from other bundles resolve
stages null or array the model stages to run: rubric, grounding, divergence, coherence. Absent means all.

Review many spec pull requests in one batch. Each pull request gets a pending review that only the person sees until they submit it on GitHub: each comment leads with a question or a fix for the author. Name the pull requests by their URLs, or name a repo: then the batch takes each open pull request that is not a draft and changes a spec doc, and requested keeps the ones that ask for the person’s review. A pull request already reviewed at its head commit is skipped, unless again. The call returns at once with the batch ID and the cost estimate; the batch runs on in Speccy. Call get_batch for its progress, and cancel_batch to stop it. Local mode only.

Input Type Required Meaning
again boolean review a pull request again although it was reviewed at its head commit
levels null or array the finding levels that go inline as comments: must, should, or both. Absent means pr.levels of the .speccy.yaml: by default MUST findings, and SHOULD findings with a suggestion.
no_attribution boolean keep the name of Speccy out of the pending reviews: no heading, no check catalog link, no hidden marker
parallel integer how many pull requests run at the same time, 1 to 10. The default is 3.
repo string a repo as owner/name, in place of urls
requested boolean with repo: only the pull requests that ask for the person’s review
stages null or array the model stages to run: rubric, grounding, divergence, coherence. Absent means all.
urls null or array the URLs of the pull requests

Review the spec docs of a GitHub URL: a file, a folder, a branch, a commit or a pull request. Speccy reads the files at the head commit with its own GitHub credential, so you copy nothing. For a pull request it reviews the spec docs that the pull request changes. No bundle is saved. The answer names the repo and the commit, and gives each doc with its verdict and its findings; each finding has its file, relative to the doc’s dir, and its line.

Input Type Required Meaning
stages null or array the model stages to run: rubric, grounding, divergence, coherence. Absent means all.
url string yes the GitHub URL of a file, a folder, a branch, a commit or a pull request

Save one file of a bundle that Speccy stores, as a new version. Give the version your edit is based on. Speccy lints the save. For a local or a GitHub bundle this tool writes nothing and says where the file is: edit that file yourself.

Input Type Required Meaning
base_version string yes the ID of the version your edit is based on: current_version.id from get_bundle
bundle string yes the bundle’s slug or ID
content string yes the whole new text of the file
path string yes the file in the bundle, such as SPEC.md

Edit the breakdown of a doc. Pass based_on, the revision you read, and ops, applied in order and all or none: split (item, trace_ids, title), merge (item, into), move_trace (trace_id, from, to; empty is no item), reorder (item, before), set_dependencies (item, depends_on), set_assignee (item, assignee), set_epic_default (epic, assignee), set_note (item, note), set_title (item or epic, title), set_repos (item, repos), move_item (item, epic), add_epic (title), remove_item (item), cover (trace_id, answer out_of_scope, covered_elsewhere or no_build, and the person’s reason), uncover (trace_id). A criterion is a quote: to change one, change the doc. Pass to_current_version instead of ops to move a stale breakdown to the doc’s current version. Make only the changes the person asked for.

Input Type Required Meaning
acknowledged boolean with to_current_version: move it although the doc is not Build Ready
based_on integer yes the revision of the breakdown you read
bundle string yes the bundle’s slug or ID
ops null or array the edits, applied in order and all or none
to_current_version boolean move a stale breakdown to the doc’s current version instead of applying ops

Verify one build against the bundle. Call it when the build from a build packet is done, with the handoff ID from HANDOFF.md. Paste the URL of the repo, branch, commit or pull request you built, or name a folder; with neither, Speccy reads the repo the doc’s implemented-by link names. Speccy finds where each requirement is implemented and tested, and gives each one an outcome: implemented, untested, unproven, missing or breached. Speccy reads the code; it never runs it and never runs the tests, so a cited test is a citation and not a pass. A missing or breached MUST opens a blocking thread on the bundle, unless you verify the head of a pull request: that run only advises. When the build covers one work item, pass work_item or trace_ids, and Speccy verifies those trace IDs only. Give a claim for a requirement when you know where it lives; leave the claims out and Speccy finds them.

Input Type Required Meaning
bundle string yes the bundle’s slug or ID
claims null or array where each requirement lives, when you know. A claim replaces what Speccy would find for that requirement, and every target in it must hold.
handoff string the handoff ID from the build packet
path string a folder on disk, instead of a repo and a commit
repo string the repo you built, as owner/name
sha string the commit you built
target string the GitHub URL of the repo, branch, commit or pull request you built, or an absolute folder path in local mode. Leave it and repo out to verify the repo that the doc’s implemented-by link names
trace_ids null or array verify only these trace IDs, when the build covers part of the doc
work_item string verify only the trace IDs of this work item: its issue URL or key, its Speccy URL, or bundle/item