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_waiver
Section titled “approve_waiver”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 |
ask_author
Section titled “ask_author”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 |
cancel_batch
Section titled “cancel_batch”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_pending
Section titled “delete_pending”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_pending
Section titled “discard_pending”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_batch
Section titled “get_batch”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_breakdown
Section titled “get_breakdown”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_bundle
Section titled “get_bundle”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_findings
Section titled “get_findings”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_questions
Section titled “get_questions”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_traceability
Section titled “get_traceability”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_verdict
Section titled “get_verdict”Get the current verdict of a bundle.
| Input | Type | Required | Meaning |
|---|---|---|---|
bundle |
string | yes | the bundle’s slug or ID |
get_work_item
Section titled “get_work_item”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 |
handoff_bundle
Section titled “handoff_bundle”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_bundles
Section titled “list_bundles”List the bundles with their verdicts.
It takes no input.
list_pending
Section titled “list_pending”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_threads
Section titled “list_threads”List the discussion threads of a bundle.
| Input | Type | Required | Meaning |
|---|---|---|---|
bundle |
string | yes | the bundle’s slug or ID |
list_waivers
Section titled “list_waivers”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_message
Section titled “post_message”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_breakdown
Section titled “propose_breakdown”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_breakdown
Section titled “push_breakdown”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_build
Section titled “report_build”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 |
request_waiver
Section titled “request_waiver”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 |
review_bundle
Section titled “review_bundle”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_content
Section titled “review_content”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_prs
Section titled “review_prs”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_url
Section titled “review_url”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_file
Section titled “save_file”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 |
update_breakdown
Section titled “update_breakdown”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_build
Section titled “verify_build”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 |