MCP tool reference
Every tool the Spectrace MCP server exposes: what it does, whether it writes, the scope it needs, and its parameters.
ai-agents/tool-reference.mdx — do not edit it by hand.Generated from allTools in packages/mcp-server/src/tools/index.ts (scopes read from the tool sources under packages/mcp-server/src/tools) by apps/web/scripts/docs/generate.ts — do not edit by hand.
Use this page to look up the name, access class, required scope, and parameters of every tool the Spectrace MCP server exposes.
The server registers 37 tools. 36 are visible to every client; 1 is an internal eval tool that stays hidden from tools/list and is rejected on call unless the server runs with SPECTRACE_ENABLE_EVAL=1. 16 tools are read-only; the rest mutate data or call an AI provider.
Terms used below:
- Access — Read-only means the tool carries the MCP
readOnlyHintannotation and does not change data. Mutating means it does not, so the server treats it as a write: it accepts an optionalclientRequestId, and re-sending the sameclientRequestIdfor the same tool, organization, and user within 24 hours returns the cached result instead of running again. Destructive marks a mutating tool that deletes data. - Scope — the permission string the server checks before the tool runs. Your effective scopes come from your organization role, further narrowed by the scopes on your API key. A call without the scope fails with
INSUFFICIENT_PERMISSIONS. See Roles and permissions and API keys. - Required — the parameter must be present. Every parameter is validated against the schema; a missing required field fails with
MISSING_REQUIRED_FIELDand a wrong value withINVALID_FIELD_VALUE.
All tools at a glance
| Tool | Group | Access | Scope |
|---|---|---|---|
spectrace_whoami | Bootstrap and discovery | Read-only | none (any valid key) |
spectrace_capabilities | Bootstrap and discovery | Read-only | none (any valid key) |
spectrace_products_list | Products | Read-only | projects:read |
spectrace_products_get | Products | Read-only | projects:read |
spectrace_products_create | Products | Mutating | projects:write |
spectrace_projects_list | Projects | Read-only | projects:read |
spectrace_projects_get | Projects | Read-only | projects:read |
spectrace_projects_create | Projects | Mutating | projects:write |
spectrace_requirements_list | Requirements and acceptance criteria | Read-only | requirements:read |
spectrace_requirements_create | Requirements and acceptance criteria | Mutating | requirements:write |
spectrace_requirements_update | Requirements and acceptance criteria | Mutating | requirements:write |
spectrace_requirements_delete | Requirements and acceptance criteria | Mutating (destructive) | requirements:delete |
spectrace_requirements_transition | Requirements and acceptance criteria | Mutating | requirements:write |
spectrace_requirements_search | Requirements and acceptance criteria | Read-only | requirements:read |
spectrace_acceptance_criteria_toggle | Requirements and acceptance criteria | Mutating | requirements:write |
spectrace_acceptance_criteria_set | Requirements and acceptance criteria | Mutating | requirements:write |
spectrace_requirements_analyze_ambiguity | Requirements and acceptance criteria | Mutating | requirements:write |
spectrace_testcases_list | Test cases | Read-only | testcases:read |
spectrace_testcases_get | Test cases | Read-only | testcases:read |
spectrace_testcases_generate | Test cases | Mutating | testcases:write |
spectrace_testcases_create | Test cases | Mutating | testcases:write |
spectrace_testcases_update | Test cases | Mutating | testcases:write |
spectrace_testcases_delete | Test cases | Mutating (destructive) | testcases:delete |
spectrace_extract_requirements | Extraction | Mutating | requirements:read |
spectrace_requirements_batch_create | Extraction | Mutating | requirements:write |
spectrace_traceability_query | Traceability | Read-only | requirements:read |
spectrace_semantic_search | Search | Read-only | requirements:read |
spectrace_approvals_request | Approvals | Mutating | approvals:write |
spectrace_approvals_grant | Approvals | Mutating | approvals:write |
spectrace_pr_verifications_create | PR verification | Mutating | verifications:write |
spectrace_pr_verifications_get | PR verification | Read-only | verifications:read |
spectrace_workflow_progress | Job progress | Read-only | requirements:read |
spectrace_workflow_next_step | Workflow guidance | Read-only | requirements:read |
spectrace_eval_run | Internal evals | Mutating · eval-only | requirements:read |
spectrace_tasks_update | Tasks and implementation context | Mutating | requirements:write |
spectrace_requirements_link_file | Tasks and implementation context | Mutating | requirements:write |
spectrace_requirements_get_context | Tasks and implementation context | Read-only | requirements:read |
Bootstrap and discovery
Who am I
spectrace_whoami — Read-only · scope: none (any valid key)
Bootstrap info: who you're authenticated as, which org, what permissions, plus a small project list (most-recently active first). Call this first when you don't know your context.
No parameters.
Source: packages/mcp-server/src/tools/system/whoami.ts
Server capabilities
spectrace_capabilities — Read-only · scope: none (any valid key)
Returns the catalog of tools, resource templates, and the caller's effective permissions. Useful for first-call discovery.
No parameters.
Source: packages/mcp-server/src/tools/system/capabilities.ts
Products
List products
spectrace_products_list — Read-only · scope: projects:read
List all products in your organization with per-product project counts. Use this to find the productId a new project should belong to, or to survey how work is organized before drilling into projects.
| Parameter | Type | Required | Description |
|---|---|---|---|
page | number (min 1) | no | Page number (default 1) |
limit | number (min 1, max 100) | no | Items per page (default 20, max 100) |
Source: packages/mcp-server/src/tools/products/list.ts
Get product
spectrace_products_get — Read-only · scope: projects:read
Get a product by ID, including its vision, domain, and child project count. Use to load product-level context before creating projects under it or reasoning about how its projects relate.
| Parameter | Type | Required | Description |
|---|---|---|---|
productId | string (uuid) | yes | UUID of the product |
Source: packages/mcp-server/src/tools/products/get.ts
Create product
spectrace_products_create — Mutating · scope: projects:write
Create a product — the top-level container that groups related projects. Use only when no existing product fits (check spectrace_products_list first); a project must belong to a product, so create the product before its first project. Slug/key are auto-generated when omitted. Pass clientRequestId for idempotency.
- annotated
idempotentHint: false: a repeated call repeats the work
| Parameter | Type | Required | Description |
|---|---|---|---|
name | string (min length 1, max length 255) | yes | |
key | string (max length 10) | no | Short product key (≤10 chars) |
description | string (max length 5000) | no | |
vision | string (max length 10000) | no | |
domain | string (max length 100) | no | |
clientRequestId | string | no | Optional client-generated identifier (UUID-style is fine). If you re-send a tool call with the same clientRequestId within 24h, the server returns the cached output of the original call instead of re-executing the mutation. Use this for any retry loop that might re-issue the same write. |
Source: packages/mcp-server/src/tools/products/create.ts
Projects
List projects
spectrace_projects_list — Read-only · scope: projects:read
List the projects you are a member of, with requirement/test-case counts. Use this to discover a project's ID (needed by every project-scoped tool) when you only know its name or key. Matches the web dashboard's project list; other org projects remain reachable by ID.
| Parameter | Type | Required | Description |
|---|---|---|---|
page | number (min 1) | no | Page number (default 1) |
limit | number (min 1, max 100) | no | Items per page (default 20, max 100) |
Source: packages/mcp-server/src/tools/projects/list.ts
Get project
spectrace_projects_get — Read-only · scope: projects:read
Get a project. detail='stats' adds requirement/test-case distributions and coverage. Use before working in an unfamiliar project to learn its key, repo, and shape.
| Parameter | Type | Required | Description |
|---|---|---|---|
projectId | string (uuid) | yes | UUID of the project |
detail | enum: summary, stats | no |
Source: packages/mcp-server/src/tools/projects/get.ts
Create project
spectrace_projects_create — Mutating · scope: projects:write
Create a new project in the caller's organization. Use when starting requirements work for a codebase/initiative that has no project yet (check spectrace_projects_list first) — every requirement lives in a project. Requires a parent productId; slug must be unique per org. Pass clientRequestId for idempotency.
- annotated
idempotentHint: false: a repeated call repeats the work
| Parameter | Type | Required | Description |
|---|---|---|---|
name | string (min length 1, max length 255) | yes | |
slug | string (min length 1, max length 100) | yes | URL-safe identifier (kebab-case, 100 chars max) |
key | string (max length 10) | no | Short prefix used in requirement ref numbers (≤10 chars) |
productId | string (min length 1, max length 36) | yes | Parent product ID for this project |
description | string (max length 5000) | no | |
githubRepoUrl | string (max length 500) | no | |
domain | enum: ecommerce, fintech, healthcare, saas, mobile, api_platform, internal_tool, other | no | |
methodology | enum: agile, kanban, waterfall, hybrid, none | no | |
complexity | enum: simple, medium, complex, enterprise | no | |
clientRequestId | string | no | Optional client-generated identifier (UUID-style is fine). If you re-send a tool call with the same clientRequestId within 24h, the server returns the cached output of the original call instead of re-executing the mutation. Use this for any retry loop that might re-issue the same write. |
Source: packages/mcp-server/src/tools/projects/create.ts
Requirements and acceptance criteria
List requirements
spectrace_requirements_list — Read-only · scope: requirements:read
List requirements in a project, filterable by status, priority, type, or workflow stage. Returns paginated rows + structuredContent. Use this to survey what exists in a project before creating or updating requirements; use spectrace_requirements_search for text matching.
| Parameter | Type | Required | Description |
|---|---|---|---|
projectId | string (uuid) | yes | UUID of the project (required) |
status | enum: draft, approved, implemented, verified | no | |
priority | enum: critical, high, medium, low | no | |
type | enum: functional, non_functional, technical, ui_ux, security, performance, integration, bug_fix | no | |
workflowStage | enum: draft, approved, qa_review, ready_for_dev, in_development, qa_verification, done | no | |
search | string | no | Search in title and description |
page | number (min 1) | no | |
limit | number (min 1, max 100) | no |
Source: packages/mcp-server/src/tools/requirements/list.ts
Create requirement
spectrace_requirements_create — Mutating · scope: requirements:write
Create a single requirement. Requires title and type. Optional userStory / acceptanceCriteria. Use spectrace_requirements_batch_create for more than ~3 at once. Pass clientRequestId to make the call idempotent. Async gap-fill enrichment runs within ~1 minute: missing artifacts (user story, AC, subtasks, tags) are generated, anything you supplied is kept verbatim, and the row is embedded for semantic search. Pass enrich: false to skip content generation — the row is still embedded.
- annotated
idempotentHint: false: a repeated call repeats the work
| Parameter | Type | Required | Description |
|---|---|---|---|
projectId | string (uuid) | yes | UUID of the project |
title | string (min length 1, max length 500) | yes | Title (1-500 chars) |
description | string (max length 100000) | no | Plain text description. Stored as both rich JSONB and plain text. |
type | enum: functional, non_functional, technical, ui_ux, security, performance, integration, bug_fix | yes | |
priority | enum: critical, high, medium, low | no | |
status | enum: draft, approved, implemented, verified | no | |
workflowStage | enum: draft, qa_review, in_development, qa_verification, done | no | |
userStory | object | no | |
userStory.asA | string | no | |
userStory.iWant | string | no | |
userStory.soThat | string | no | |
acceptanceCriteria | object[] | no | |
acceptanceCriteria[].id | string | no | |
acceptanceCriteria[].description | string | yes | |
acceptanceCriteria[].completed | boolean | no | |
tags | string[] | no | |
enrich | boolean | no | Default true: async gap-fill enrichment generates missing artifacts and embeds the row for semantic search. false: skip content generation; the row is still embedded. |
clientRequestId | string | no | Optional client-generated identifier (UUID-style is fine). If you re-send a tool call with the same clientRequestId within 24h, the server returns the cached output of the original call instead of re-executing the mutation. Use this for any retry loop that might re-issue the same write. |
Source: packages/mcp-server/src/tools/requirements/create.ts
Update requirement
spectrace_requirements_update — Mutating · scope: requirements:write
Update a requirement's fields in place. Pass only the fields to change. Use this for content edits (title, description, priority, tags); use spectrace_requirements_transition for workflow-stage moves to get state-machine validation.
- annotated
idempotentHint: repeating the call has the same effect as calling it once
| Parameter | Type | Required | Description |
|---|---|---|---|
requirementId | string (uuid) | yes | |
title | string (max length 500) | no | |
description | string (max length 100000) | no | |
type | enum: functional, non_functional, technical, ui_ux, security, performance, integration, bug_fix | no | |
priority | enum: critical, high, medium, low | no | |
status | enum: draft, approved, implemented, verified | no | |
workflowStage | enum: draft, qa_review, ready_for_dev, in_development, qa_verification, done | no | |
tags | string[] | no | |
clientRequestId | string | no | Optional client-generated identifier (UUID-style is fine). If you re-send a tool call with the same clientRequestId within 24h, the server returns the cached output of the original call instead of re-executing the mutation. Use this for any retry loop that might re-issue the same write. |
Source: packages/mcp-server/src/tools/requirements/update.ts
Delete requirement
spectrace_requirements_delete — Mutating (destructive) · scope: requirements:delete
Permanently delete a requirement. Cascades to test cases, AC, and tasks; traceability links that reference the requirement are left in place. Cannot be undone — confirm with the user before deleting anything they did not explicitly ask to remove.
- annotated
idempotentHint: repeating the call has the same effect as calling it once
| Parameter | Type | Required | Description |
|---|---|---|---|
requirementId | string (uuid) | yes | |
clientRequestId | string | no | Optional client-generated identifier (UUID-style is fine). If you re-send a tool call with the same clientRequestId within 24h, the server returns the cached output of the original call instead of re-executing the mutation. Use this for any retry loop that might re-issue the same write. |
Source: packages/mcp-server/src/tools/requirements/delete.ts
Transition requirement
spectrace_requirements_transition — Mutating · scope: requirements:write
Move a requirement to the next workflow stage with state-machine validation. Valid stages: draft → qa_review → in_development → qa_verification → done (plus restricted backward moves). Prefer this over spectrace_requirements_update for stage changes.
- annotated
idempotentHint: repeating the call has the same effect as calling it once
| Parameter | Type | Required | Description |
|---|---|---|---|
requirementId | string (uuid) | yes | |
targetStage | enum: draft, qa_review, in_development, qa_verification, done | yes | |
clientRequestId | string | no | Optional client-generated identifier (UUID-style is fine). If you re-send a tool call with the same clientRequestId within 24h, the server returns the cached output of the original call instead of re-executing the mutation. Use this for any retry loop that might re-issue the same write. |
Source: packages/mcp-server/src/tools/requirements/transition.ts
Search requirements
spectrace_requirements_search — Read-only · scope: requirements:read
Keyword (ILIKE) search across requirement title and description, org-wide or scoped to one project. Use this when hunting for a requirement by words you remember; use spectrace_semantic_search for meaning-based matching and spectrace_requirements_list for filtered browsing.
| Parameter | Type | Required | Description |
|---|---|---|---|
query | string (min length 2, max length 200) | yes | 2+ characters |
projectId | string (uuid) | no | |
page | number (min 1) | no | |
limit | number (min 1, max 100) | no |
Source: packages/mcp-server/src/tools/requirements/search.ts
Toggle acceptance criterion
spectrace_acceptance_criteria_toggle — Mutating · scope: requirements:write
Toggle (or explicitly set) the completed flag on a single acceptance criterion by id. Use this to record progress as individual criteria are met; use spectrace_acceptance_criteria_set for bulk edits. Returns the updated AC list with completion counts.
- annotated
idempotentHint: repeating the call has the same effect as calling it once
| Parameter | Type | Required | Description |
|---|---|---|---|
requirementId | string (uuid) | yes | |
criterionId | string (min length 1) | yes | The id field of the AC item (e.g. 'ac-1' or a UUID-style id). |
completed | boolean | no | If omitted, flips the current value. If provided, sets to this value. |
clientRequestId | string | no | Optional client-generated identifier (UUID-style is fine). If you re-send a tool call with the same clientRequestId within 24h, the server returns the cached output of the original call instead of re-executing the mutation. Use this for any retry loop that might re-issue the same write. |
Source: packages/mcp-server/src/tools/requirements/ac-toggle.ts
Set acceptance criteria
spectrace_acceptance_criteria_set — Mutating · scope: requirements:write
Bulk-edit acceptance criteria on a requirement. mode=replace overwrites the array; mode=append adds new items; mode=edit patches items by id. Use this for multi-item changes; use spectrace_acceptance_criteria_toggle to flip a single item's completed flag.
- annotated
idempotentHint: repeating the call has the same effect as calling it once
| Parameter | Type | Required | Description |
|---|---|---|---|
requirementId | string (uuid) | yes | |
mode | enum: replace, append, edit | yes | |
items | object[] | yes | AC items. For mode=edit each item must include id. For append/replace id is optional and auto-assigned. |
items[].id | string | no | |
items[].description | string | no | |
items[].completed | boolean | no | |
clientRequestId | string | no | Optional client-generated identifier (UUID-style is fine). If you re-send a tool call with the same clientRequestId within 24h, the server returns the cached output of the original call instead of re-executing the mutation. Use this for any retry loop that might re-issue the same write. |
Source: packages/mcp-server/src/tools/requirements/ac-set.ts
Analyze requirement ambiguity
spectrace_requirements_analyze_ambiguity — Mutating · scope: requirements:write
Score a requirement's clarity (0=clear, 1=very ambiguous) and return a list of vague phrases with concrete alternatives. Use before approving or implementing a requirement to surface wording that needs tightening. By default persists the result on the requirement.
- annotated
openWorldHint: calls out to an AI provider
| Parameter | Type | Required | Description |
|---|---|---|---|
requirementId | string (uuid) | yes | |
persist | boolean | no | Save the analysis to requirements.ambiguity_score/_analysis. Default true. |
clientRequestId | string | no | Optional client-generated identifier (UUID-style is fine). If you re-send a tool call with the same clientRequestId within 24h, the server returns the cached output of the original call instead of re-executing the mutation. Use this for any retry loop that might re-issue the same write. |
Source: packages/mcp-server/src/tools/requirements/analyze-ambiguity.ts
Test cases
List test cases
spectrace_testcases_list — Read-only · scope: testcases:read
List test cases scoped to a requirement or project, with optional status / review-status filters. Use to survey existing coverage before generating or creating new test cases, or to find cases awaiting review.
| Parameter | Type | Required | Description |
|---|---|---|---|
requirementId | string (uuid) | no | |
projectId | string (uuid) | no | |
status | enum: draft, approved, generated, pr_created | no | |
reviewStatus | enum: pending, approved, rejected | no | |
page | number (min 1) | no | |
limit | number (min 1, max 100) | no |
Source: packages/mcp-server/src/tools/test-cases/list.ts
Get test case
spectrace_testcases_get — Read-only · scope: testcases:read
Get a single test case by UUID — full Gherkin, description, status, review state, and parent requirement. Use when a list result or requirement context references a test case you need in full.
| Parameter | Type | Required | Description |
|---|---|---|---|
testCaseId | string (uuid) | yes |
Source: packages/mcp-server/src/tools/test-cases/get.ts
Generate test cases
spectrace_testcases_generate — Mutating · scope: testcases:write
Generate Gherkin test case suggestions for a requirement and (by default) persist them as test cases with status generated and review status pending. Returns structured suggestions in structuredContent.suggestions.
- annotated
idempotentHint: false: a repeated call repeats the work - annotated
openWorldHint: calls out to an AI provider
| Parameter | Type | Required | Description |
|---|---|---|---|
requirementId | string (uuid) | yes | |
count | number (min 1, max 10) | no | Number to generate (1-10, default 3) |
includeEdgeCases | boolean | no | |
includeNegativeTests | boolean | no | |
persist | boolean | no | Insert as test cases with status generated. Default true. |
clientRequestId | string | no | Optional client-generated identifier (UUID-style is fine). If you re-send a tool call with the same clientRequestId within 24h, the server returns the cached output of the original call instead of re-executing the mutation. Use this for any retry loop that might re-issue the same write. |
Source: packages/mcp-server/src/tools/test-cases/generate.ts
Create test case
spectrace_testcases_create — Mutating · scope: testcases:write
Create a test case for a requirement. Provide Gherkin (Given/When/Then) and optional plain description / manual steps. Use for hand-written cases; prefer spectrace_testcases_generate for AI-suggested coverage. Pass clientRequestId for idempotency.
- annotated
idempotentHint: false: a repeated call repeats the work
| Parameter | Type | Required | Description |
|---|---|---|---|
requirementId | string (uuid) | yes | |
title | string (min length 1, max length 500) | yes | |
gherkin | string (min length 1, max length 10000) | yes | |
description | string (max length 100000) | no | |
steps | object[] | no | |
steps[].step | number | no | |
steps[].action | string | no | |
steps[].expectedResult | string | no | |
aiGenerated | boolean | no | Mark as AI-suggested (default false) |
clientRequestId | string | no | Optional client-generated identifier (UUID-style is fine). If you re-send a tool call with the same clientRequestId within 24h, the server returns the cached output of the original call instead of re-executing the mutation. Use this for any retry loop that might re-issue the same write. |
Source: packages/mcp-server/src/tools/test-cases/create.ts
Update test case
spectrace_testcases_update — Mutating · scope: testcases:write
Update a test case's title, description, Gherkin, status, or review status. Use after refining a generated case, or to approve/reject during review (setting reviewStatus records you as the reviewer). Only the fields you pass are changed.
- annotated
idempotentHint: repeating the call has the same effect as calling it once
| Parameter | Type | Required | Description |
|---|---|---|---|
testCaseId | string (uuid) | yes | |
title | string (max length 500) | no | |
description | string (max length 100000) | no | |
gherkin | string (max length 100000) | no | |
status | enum: draft, approved, generated, pr_created | no | |
reviewStatus | enum: pending, approved, rejected | no | |
clientRequestId | string | no | Optional client-generated identifier (UUID-style is fine). If you re-send a tool call with the same clientRequestId within 24h, the server returns the cached output of the original call instead of re-executing the mutation. Use this for any retry loop that might re-issue the same write. |
Source: packages/mcp-server/src/tools/test-cases/update.ts
Delete test case
spectrace_testcases_delete — Mutating (destructive) · scope: testcases:delete
Permanently delete a test case. Use to remove duplicates or cases that no longer apply — this cannot be undone; to merely mark a case as not applicable, set reviewStatus: 'rejected' via spectrace_testcases_update instead.
- annotated
idempotentHint: repeating the call has the same effect as calling it once
| Parameter | Type | Required | Description |
|---|---|---|---|
testCaseId | string (uuid) | yes | |
clientRequestId | string | no | Optional client-generated identifier (UUID-style is fine). If you re-send a tool call with the same clientRequestId within 24h, the server returns the cached output of the original call instead of re-executing the mutation. Use this for any retry loop that might re-issue the same write. |
Source: packages/mcp-server/src/tools/test-cases/delete.ts
Extraction
Extract requirements
spectrace_extract_requirements — Mutating · scope: requirements:read
Extract draft requirements + AC from raw text using Spectrace's AI agent. Use when turning a spec, PRD, ticket, or conversation into structured requirements instead of writing them by hand. Output is reviewable — pass it to spectrace_requirements_batch_create to persist (idempotent via clientRequestId).
- annotated
idempotentHint: false: a repeated call repeats the work - annotated
openWorldHint: calls out to an AI provider
| Parameter | Type | Required | Description |
|---|---|---|---|
projectId | string (uuid) | yes | UUID of the project (used to scope domain context). |
text | string (min length 50, max length 100000) | yes | Raw text to extract from (50-100k characters). |
sourceType | enum: text, document, conversation, url | no | |
generateUserStories | boolean | no | |
generateAcceptanceCriteria | boolean | no | |
userNotes | string (max length 4000) | no | Optional hints for the extractor. |
clientRequestId | string | no | Optional client-generated identifier (UUID-style is fine). If you re-send a tool call with the same clientRequestId within 24h, the server returns the cached output of the original call instead of re-executing the mutation. Use this for any retry loop that might re-issue the same write. |
Source: packages/mcp-server/src/tools/extraction/extract.ts
Batch-create requirements
spectrace_requirements_batch_create — Mutating · scope: requirements:write
Bulk-insert requirements (e.g., from spectrace_extract_requirements output). Use instead of repeated spectrace_requirements_create calls when persisting more than ~3 at once. Single transaction; rollback on error; per-item sourceId dedupes reruns. Pass clientRequestId to dedupe retries. Newly inserted rows get async gap-fill enrichment + embedding (missing artifacts generated, supplied content kept verbatim); pass enrich: false to skip content generation — rows are still embedded. Skipped duplicates are never re-enriched.
- annotated
idempotentHint: false: a repeated call repeats the work
| Parameter | Type | Required | Description |
|---|---|---|---|
projectId | string (uuid) | yes | |
requirements | object[] (min items 1, max items 100) | yes | |
requirements[].title | string | yes | |
requirements[].description | string | no | |
requirements[].type | enum: functional, non_functional, technical, ui_ux, security, performance, integration, bug_fix | no | |
requirements[].priority | enum: critical, high, medium, low | no | |
requirements[].userStory | object | no | |
requirements[].userStory.asA | string | no | |
requirements[].userStory.iWant | string | no | |
requirements[].userStory.soThat | string | no | |
requirements[].acceptanceCriteria | array of string or object | no | |
requirements[].acceptanceCriteria[].id | string | no | |
requirements[].acceptanceCriteria[].description | string | yes | |
requirements[].acceptanceCriteria[].completed | boolean | no | |
requirements[].tags | string[] | no | |
requirements[].sourceId | string | no | Idempotency key per item (e.g. external issue id) |
requirements[].sourceType | enum: native, linear, jira, github_issue | no | |
requirements[].sourceUrl | string | no | |
enrich | boolean | no | Default true: newly inserted rows get async gap-fill enrichment + embedding. false: skip content generation; rows are still embedded. |
clientRequestId | string | no | Optional client-generated identifier (UUID-style is fine). If you re-send a tool call with the same clientRequestId within 24h, the server returns the cached output of the original call instead of re-executing the mutation. Use this for any retry loop that might re-issue the same write. |
Source: packages/mcp-server/src/tools/extraction/batch-create.ts
Traceability
Query traceability
spectrace_traceability_query — Read-only · scope: requirements:read
Trace relationships between requirements, test cases, and code files — e.g. before changing a requirement (what depends on it?) or a file (which requirements does it implement?). Direction is meaningful for requirement→requirement queries (upstream/downstream/both); other types ignore it.
| Parameter | Type | Required | Description |
|---|---|---|---|
from | object | yes | |
from.type | enum: requirement, test_case, file | yes | |
from.id | string | yes | UUID for requirement/test_case, or file path for file |
direction | enum: upstream, downstream, both | no |
Source: packages/mcp-server/src/tools/traceability/query.ts
Search
Semantic search
spectrace_semantic_search — Read-only · scope: requirements:read
Vector similarity search over indexed requirements or code chunks. Use for concept-level questions ('what touches authentication?') instead of listing everything and reading each item. Returns ranked rows. Requires the project to have been embedded — un-embedded rows are skipped.
| Parameter | Type | Required | Description |
|---|---|---|---|
projectId | string (uuid) | yes | |
query | string (min length 2, max length 2000) | yes | |
entity | enum: requirement, code, test_case | yes | Which corpus to search. test_case is title+gherkin via requirement embedding. |
limit | number | no | 1-25, default 10 |
Source: packages/mcp-server/src/tools/search/semantic.ts
Approvals
Request approval
spectrace_approvals_request — Mutating · scope: approvals:write
Open an approval request for a workflow transition. Use before moving a requirement between stages when approval rules may govern the transition. If no approval_rules apply, returns success with created=0 — the move is unrestricted. Re-requesting an already-pending transition returns the existing request.
- annotated
idempotentHint: repeating the call has the same effect as calling it once
| Parameter | Type | Required | Description |
|---|---|---|---|
requirementId | string (uuid) | yes | |
fromStage | enum: draft, qa_review, ready_for_dev, in_development, qa_verification, done | yes | |
toStage | enum: draft, qa_review, ready_for_dev, in_development, qa_verification, done | yes | |
clientRequestId | string | no | Optional client-generated identifier (UUID-style is fine). If you re-send a tool call with the same clientRequestId within 24h, the server returns the cached output of the original call instead of re-executing the mutation. Use this for any retry loop that might re-issue the same write. |
Source: packages/mcp-server/src/tools/approvals/request.ts
Grant or reject approval
spectrace_approvals_grant — Mutating · scope: approvals:write
Approve or reject a pending approval request (from spectrace_approvals_request). Use when acting as the approver on a gated workflow transition; approving the last pending request advances the requirement's workflow stage.
- annotated
idempotentHint: repeating the call has the same effect as calling it once
| Parameter | Type | Required | Description |
|---|---|---|---|
approvalRequestId | string (uuid) | yes | |
decision | enum: approved, rejected | yes | |
comment | string (max length 4000) | no | |
clientRequestId | string | no | Optional client-generated identifier (UUID-style is fine). If you re-send a tool call with the same clientRequestId within 24h, the server returns the cached output of the original call instead of re-executing the mutation. Use this for any retry loop that might re-issue the same write. |
Source: packages/mcp-server/src/tools/approvals/grant.ts
PR verification
Verify PR against requirement
spectrace_pr_verifications_create — Mutating · scope: verifications:write
Verify a PR against a requirement's acceptance criteria. mode='inline' runs the AI verifier NOW against a diff you supply and persists the result — use this when you want a verdict; an inline rerun for the same (project, prNumber, headSha) REPLACES the prior result. mode='register' (default) links the PR to the requirement; the GitHub App webhook honours that link on the next push (rung 0 of requirement resolution) and it beats branch/title refs. Register returns no score and polling it does not produce one.
- annotated
idempotentHint: false: a repeated call repeats the work - annotated
openWorldHint: calls out to an AI provider
| Parameter | Type | Required | Description |
|---|---|---|---|
requirementId | string (uuid) | yes | |
prNumber | number | yes | |
prUrl | string (min length 1, max length 500) | yes | |
prTitle | string (max length 500) | no | |
prAuthor | string (max length 100) | no | |
repoFullName | string (max length 255) | no | Repository in owner/name form, e.g. 'spectrace-io/spectrace'. When omitted, the project's GitHub repo URL is used; if the project has none, the run is stored with repo 'unknown'. |
headSha | string (min length 7, max length 40) | yes | Commit SHA (7-40 characters). Use the full 40-character SHA so reruns and the GitHub webhook match the same run. |
baseSha | string (max length 40) | no | |
mode | enum: register, inline | no | |
prDiff | object[] | no | Required for inline mode. Array of file diff objects. |
prDiff[].filename | string | no | |
prDiff[].status | string | no | |
prDiff[].additions | number | no | |
prDiff[].deletions | number | no | |
prDiff[].patch | string | no | |
prBody | string | no | PR body for inline mode. |
clientRequestId | string | no | Optional client-generated identifier (UUID-style is fine). If you re-send a tool call with the same clientRequestId within 24h, the server returns the cached output of the original call instead of re-executing the mutation. Use this for any retry loop that might re-issue the same write. |
Source: packages/mcp-server/src/tools/verifications/create.ts
Get PR verification
spectrace_pr_verifications_get — Read-only · scope: verifications:read
Fetch a PR verification run by id OR by (projectId, prNumber, headSha). Use it to read the result of an inline run, check whether the webhook has verified a registered PR, or review past results. Returns overall score and per-requirement results.
| Parameter | Type | Required | Description |
|---|---|---|---|
verificationId | string (uuid) | no | |
projectId | string (uuid) | no | |
prNumber | number | no | |
headSha | string | no |
Source: packages/mcp-server/src/tools/verifications/get.ts
Job progress
Poll job progress
spectrace_workflow_progress — Read-only · scope: requirements:read
Poll progress on a long-running operation (test generation, doc import, PR verification). Pass jobRunId or verificationId.
| Parameter | Type | Required | Description |
|---|---|---|---|
jobRunId | string (uuid) | no | UUID of the background job run |
verificationId | string (uuid) | no | UUID of the PR verification |
Source: packages/mcp-server/src/tools/jobs/progress.ts
Workflow guidance
Suggest next workflow step
spectrace_workflow_next_step — Read-only · scope: requirements:read
Given a requirement, suggest the next concrete action an agent should take (e.g. 'AC-3 has no test case — call spectrace_testcases_generate then transition to qa_review'). Returns blocking items first.
| Parameter | Type | Required | Description |
|---|---|---|---|
requirementId | string (uuid) | yes | UUID of the requirement |
Source: packages/mcp-server/src/tools/workflow/next-step.ts
Internal evals
Hidden unless the server runs with SPECTRACE_ENABLE_EVAL=1. Without it these tools are omitted from tools/list and any call is rejected.
Run AI evals
spectrace_eval_run — Mutating · scope: requirements:read
Run a curated smoke eval against Spectrace's own AI agents (ambiguity analyzer, requirements extractor). Use to check for quality regressions after changing prompts, models, or provider config — not for evaluating user requirements.
- eval-only — hidden unless
SPECTRACE_ENABLE_EVAL=1 - annotated
idempotentHint: false: a repeated call repeats the work - annotated
openWorldHint: calls out to an AI provider
| Parameter | Type | Required | Description |
|---|---|---|---|
eval | enum: ambiguity_smoke, extraction_smoke, all | no | |
clientRequestId | string | no | Optional client-generated identifier (UUID-style is fine). If you re-send a tool call with the same clientRequestId within 24h, the server returns the cached output of the original call instead of re-executing the mutation. Use this for any retry loop that might re-issue the same write. |
Source: packages/mcp-server/src/tools/eval/run.ts
Tasks and implementation context
Update subtask
spectrace_tasks_update — Mutating · scope: requirements:write
Set a subtask's status (todo/in_progress/done) and optionally its title. Call as you start and finish each subtask while implementing a requirement — it recomputes the parent requirement's progress_percentage.
- annotated
idempotentHint: repeating the call has the same effect as calling it once
| Parameter | Type | Required | Description |
|---|---|---|---|
requirementId | string (uuid) | yes | |
taskId | string (uuid) | yes | |
status | enum: todo, in_progress, done | yes | |
title | string (max length 255) | no | |
clientRequestId | string | no | Optional client-generated identifier (UUID-style is fine). If you re-send a tool call with the same clientRequestId within 24h, the server returns the cached output of the original call instead of re-executing the mutation. Use this for any retry loop that might re-issue the same write. |
Source: packages/mcp-server/src/tools/tasks/update.ts
Link file to requirement
spectrace_requirements_link_file — Mutating · scope: requirements:write
Link a code file path to a requirement for traceability. Call while implementing so coverage views and PR verification know which files realize the requirement. Idempotent — a duplicate path is a no-op.
- annotated
idempotentHint: repeating the call has the same effect as calling it once
| Parameter | Type | Required | Description |
|---|---|---|---|
requirementId | string (uuid) | yes | |
filePath | string (min length 1, max length 500) | yes | |
clientRequestId | string | no | Optional client-generated identifier (UUID-style is fine). If you re-send a tool call with the same clientRequestId within 24h, the server returns the cached output of the original call instead of re-executing the mutation. Use this for any retry loop that might re-issue the same write. |
Source: packages/mcp-server/src/tools/tasks/link-file.ts
Get requirement context
spectrace_requirements_get_context — Read-only · scope: requirements:read
Get full implementation context for a requirement (user story, AC, subtasks, test cases, linked files, project info). Use before starting to implement.
| Parameter | Type | Required | Description |
|---|---|---|---|
requirementId | string (uuid) | yes |
Source: packages/mcp-server/src/tools/tasks/get-context.ts