wuxnz/speck-it-mcp-server

Speck-It MCP Server

Website Speck-It MCP Server Website

The Speck-It MCP Server adapts GitHub's Spec Kit workflow into a Model Context Protocol (MCP) service. It enables coding agents to generate specifications, implementation plans, task checklists, and execution playbooks directly within a project workspace. All generated artifacts are stored beneath the project's .speck-it/ directory.

Features

• Spec generation via generate_spec with constitution-aware summaries and clarifications.
• Implementation planning through generate_plan, producing phase-oriented guidance.
• Enhanced task management with manage_project_tasks supporting create, list, update, validate, get_next, get_status, and auto_update actions.
• Execution tasks with generate_tasks, list_tasks, update_task, next_task, and complete_task to track progress.
• Advanced task tracking using ProjectTask and ProjectStatus classes for comprehensive project oversight.
• Governance hooks including set_constitution, get_constitution, feature_status, and finalize_feature.
• Root registration utilities (set_feature_root) to ensure artifacts resolve to the correct project.
• Centralized auto-updates that automatically update task statuses across all workflow stages (constitution setting, feature root registration, spec generation, plan creation, and task generation).

Quick Start

1. Install dependencies

   uv sync
   

2. Run the MCP server

   uv run python main.py
   

   The server communicates over stdio by default. Configure your MCP-compatible agent (e.g., Windsurf, Roo Code, Cline) to launch this command.

3. Connect an agent

   • Point the agent at the command above.
   • Supply root arguments or call set_feature_root if the agent executes outside the project tree.

Example MCP Client Configuration

Below is a sample MCP configuration snippet that launches this server via uv:

{
  "mcpServers": {
    "speck-it": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp[cli]",
        "mcp",
        "run",
        "<path-to-repo>/main.py"
      ],
      "disabledTools": []
    }
  }
}

Tooling Overview

• Workspace setup: set_constitution, get_constitution, list_features.
• Specification pipeline: generate_spec, generate_plan, generate_tasks.
• Enhanced project management: manage_project_tasks with comprehensive task operations (create, list, update, validate, get_next, get_status, auto_update).
• Task execution: list_tasks, update_task, next_task, complete_task, feature_status, finalize_feature.
• Project binding: set_feature_root to register the correct artifact root when auto-detection is insufficient.
• Advanced tracking: ProjectTask and ProjectStatus classes for detailed project oversight and milestone tracking.

Storage Layout

Artifacts are written under .speck-it/ by default:

.speck-it/
├── memory/
│   └── constitution.md
├── specs/
│   └── <feature-id>/
│       ├── spec.md
│       ├── plan.md
│       ├── tasks.md
│       └── analysis.json
└── state/
    └── <feature-id>_status.json

Set the SPECKIT_STORAGE_DIR environment variable to switch to an alternate directory name.

Enhanced Project Management

The Speck-It MCP Server now includes advanced project management capabilities that provide comprehensive task tracking and workflow automation:

Centralized Task Management

The manage_project_tasks function provides a unified interface for all task operations:

• Task Creation: Create tasks with priorities, dependencies, prerequisites, and time estimates
• Task Listing: Filter and sort tasks by status, feature, type, or priority range
• Task Updates: Modify task status, add notes, update priorities, and track actual hours
• Prerequisite Validation: Ensure tasks meet all requirements before execution
• Next Task Discovery: Automatically identify ready-to-execute tasks across all features
• Project Status Overview: Comprehensive status reporting with feature breakdowns
• Auto-Updates: Automatically update task statuses based on workflow milestones

Enhanced Task Classes

• ProjectTask: Advanced task representation with metadata, dependencies, and progress tracking
• ProjectStatus: Project-level status aggregation across all features and milestones

Workflow Integration

All workflow stages now automatically update project tasks:

• Setting constitution → Marks global workflow tasks complete
• Registering feature root → Unlocks specification generation tasks
• Generating specifications → Transitions to planning phase
• Creating implementation plans → Unlocks development tasks
• Generating task lists → Enables execution phase

This ensures complete traceability and automatic workflow progression throughout the development lifecycle.

Development

• Create a virtual environment or rely on uv's managed environment (uv venv).
• Run formatting and tests before committing:

  uv run pytest
  

• Regenerate specs or plans when changing NLP heuristics in lib/speckit.py to keep templates up to date.

Workflow Steps

• Step 1 — Constitution: set_constitution was used to enforce TypeScript, shadcn/ui, reusable patterns, strong typing, and Zustand for state needs. The system automatically updates project tasks to reflect this milestone.
• Step 2 — Root Registration: set_feature_root recorded the project directory so all artifacts write to the correct .speck-it/ tree. Task statuses are automatically updated to unlock the next workflow stage.
• Step 3 — Specification: generate_spec captured the high-level goals for a SaaS-inspired portfolio with dark mode, animations, and rich sections filled with placeholders. The enhanced task management system automatically marks specification tasks as complete.
• Step 4 — Planning: generate_plan produced a detailed implementation roadmap aligning engineering tasks with the constitution. Project tasks are auto-updated to reflect planning completion and unlock implementation tasks.
• Step 5 — Task Authoring: generate_tasks converted the plan into a TDD-friendly checklist stored in tasks.md. The system uses manage_project_tasks to automatically transition from planning to execution phase.
• Step 6 — Execution: Each checklist item was implemented and closed via update_task and complete_task, with full traceability through the enhanced ProjectTask and ProjectStatus classes, producing the full Next.js + TypeScript + shadcn/ui experience.

Example Output: Next.js + TypeScript + shadcn/ui Portfolio

This repository includes a fully generated developer portfolio that showcases how the MCP server guides an agent from constitution setup through task completion. It was generated by running the MCP server against the shadcn/ui init project with "Grok Code Fast 1" in Windsurf. The screenshots reside in screenshots/example-outputs/nextjs-dev-portfolio/.

Screenshots

Additional sections (projects, experience, education, and contact) follow the same visual system and can be regenerated by re-running the workflow steps above.

License

• Project code is provided under the BSD 3-Clause License (see LICENSE).
• Portions derived from GitHub's Spec Kit remain subject to the MIT License; the full text is reproduced in LICENSE.