MCP Tools

Complete reference for all 22 SpecForge MCP tools — parameters, usage, and examples.

SpecForge exposes 22 MCP tools organized in five categories. These tools are available to any MCP-compatible coding agent (Claude Code, Cursor, VS Code with Copilot, Gemini CLI, etc.) once the SpecForge MCP server is configured.

Queries

Six tools for reading project data, searching tickets, and generating reports. These are read-only — they never modify your specification.

get

Retrieves a single entity by type and ID.

{
  "type": "ticket",
  "id": "tkt_abc123",
  "specificationId": "spec_xyz789"
}

Returns the complete ticket object including title, description, steps, acceptance criteria, dependencies, status, complexity, priority, tags, and file expectations.

list

Lists entities of a given type with optional filters.

{
  "type": "tickets",
  "specificationId": "spec_xyz789",
  "epicId": "epic_456"
}

Returns an array of all tickets belonging to the specified epic.

search

Unified search across tickets with full-text queries and structured filters.

{
  "query": "authentication middleware",
  "status": ["ready", "pending"],
  "priority": ["high", "critical"],
  "limit": 10
}

✅ Combine files with tags to find all tickets touching a specific part of your codebase. For example, files: ["src/auth/**"] with tags: ["security"].

get_next_actionable_tickets

Returns tickets in ready status with all dependencies satisfied, ordered by priority and complexity.

{
  "specificationId": "spec_xyz789",
  "limit": 5
}

This is the primary entry point for agents deciding what to work on next. In Agent Teams, the orchestrator calls this to assign tickets to workers.

get_blocked_tickets

Returns tickets in pending status along with the reasons they’re blocked.

Each blocked ticket includes its unresolved dependencies and any external block reasons.

get_report

Generates analytical reports at different scopes and time ranges.

Lifecycle

Nine tools that drive specifications through planning, implementation, and review. These are the core workflow tools.

start_planning_session

Opens a planning session for a specification, enabling structural changes.

The specification must be in draft, planning, specifying, or validating state.

action_planning_session

Performs operations within an active planning session. This is the primary tool for building specifications — it handles 18 distinct operations.

Additional parameters depend on the operation.

Structure Operations

Linking Operations

Query & Control Operations

Example — Creating a ticket:

{
  "specificationId": "spec_xyz789",
  "operation": "create_ticket",
  "epicId": "epic_456",
  "title": "Implement JWT token generation",
  "description": "Create a service that generates signed JWT access tokens with configurable expiration.",
  "complexity": "medium",
  "priority": "high",
  "steps": [
    "Create JwtService class in src/auth/jwt.service.ts",
    "Implement generateAccessToken method with RS256 signing",
    "Add token expiration configuration via environment variables",
    "Write unit tests for token generation and validation"
  ],
  "acceptanceCriteria": [
    "Tokens are signed with RS256 algorithm",
    "Token expiration is configurable",
    "Invalid tokens are rejected with clear error messages"
  ]
}

ℹ️ The specification transitions automatically between planning, specifying, and validating states based on the operations you perform. You don’t manage these transitions manually.

complete_planning_session

Ends the planning session and triggers the Planning Review gate.

If the Planning Review gate is enabled and the specification passes, it advances to ready.

start_work_session

Begins implementation work on a specific ticket.

Transitions the ticket from ready to active. Returns the full ticket context: implementation steps, acceptance criteria, file expectations, dependency outputs, and linked blueprints.

action_work_session

Records progress, results, and discoveries during implementation.

{
  "ticketId": "tkt_abc123",
  "steps": [
    { "index": 0, "completed": true },
    { "index": 1, "completed": true }
  ],
  "files": [
    { "path": "src/auth/jwt.service.ts", "action": "created" },
    { "path": "src/auth/jwt.service.test.ts", "action": "created" }
  ],
  "notes": "Used jose library instead of jsonwebtoken for Edge Runtime compatibility."
}

complete_work_session

Finalizes work on a ticket with a summary and validation results.

Transitions the ticket from active to done. Dependent tickets are recalculated and may become ready.

start_review_session

Begins an Implementation Review session for a specification.

action_review_session

Addresses findings during an active review session.

complete_review_session

Concludes the Implementation Review.

Mutations

Four tools for creating, modifying, and linking project data.

create_specification

Creates a new specification within a project.

reopen_specification

Reopens a completed or reviewed specification for additional work.

reset_work_session

Resets completed tickets back to a workable state.

⚠️ Resetting tickets clears work session data. Linked commits and PRs are preserved, but step completions, notes, and acceptance criteria results are removed. Resetting cascades to dependent tickets.

link_pull_request

Associates a pull request with a completed ticket.

Orchestration

Two tools for understanding and navigating the dependency graph.

get_critical_path

Calculates the longest dependency chain in a specification — the sequence of tickets that determines the minimum time to completion.

Returns an ordered list of tickets forming the critical path, along with total estimated effort.

get_dependency_tree

Renders the complete upstream and downstream dependency tree for a specification.

Returns a tree structure showing all tickets, their dependencies, and current statuses. Useful for visualizing the overall shape of work and identifying bottlenecks.

Utility

feedback

Submit feedback, report issues, or suggest improvements.

See Also

• CLI Commands — CLI equivalents for common operations
• Specification States — State machine triggered by lifecycle tools
• Ticket States — Ticket states driven by work session tools