README.md•8.42 kB
# Spec Workflow MCP
[](https://www.npmjs.com/package/spec-workflow-mcp)
[](https://opensource.org/licenses/MIT)
[](https://modelcontextprotocol.com)
[English](README.md) | [简体中文](README-zh.md)
Guide AI to systematically complete software development through a structured **Requirements → Design → Tasks** workflow, ensuring code implementation stays aligned with business needs.
## Why Use It?
### ❌ Without Spec Workflow
- AI jumps randomly between tasks, lacking systematic approach
- Requirements disconnect from actual code implementation
- Scattered documentation, difficult to track project progress
- Missing design decision records
### ✅ With Spec Workflow
- AI completes tasks sequentially, maintaining focus and context
- Complete traceability from user stories to code implementation
- Standardized document templates with automatic progress management
- Each stage requires confirmation, ensuring correct direction
- **Persistent progress**: Continue from where you left off with `check`, even in new conversations
## Recent Updates
> **v1.0.7**
> - 🎯 Improved reliability for most models to manage tasks with spec workflow
>
> **v1.0.6**
> - ✨ Batch task completion: Complete multiple tasks at once for faster progress on large projects
>
> **v1.0.5**
> - 🐛 Edge case fixes: Distinguish between "task not found" and "task already completed" to prevent workflow interruption
>
> **v1.0.4**
> - ✅ Task management: Added task completion tracking for systematic project progression
>
> **v1.0.3**
> - 🎉 Initial release: Core workflow framework for Requirements → Design → Tasks
## Quick Start
### 1. Install (Claude Code Example)
```bash
claude mcp add spec-workflow-mcp -s user -- npx -y spec-workflow-mcp@latest
```
See [full installation guide](#installation) for other clients.
### 2. Start a New Project
```
"Help me use spec workflow to create a user authentication system"
```
### 3. Continue Existing Project
```
"Use spec workflow to check ./my-project"
```
The AI will automatically detect project status and continue from where it left off.
## Workflow Example
### 1. You describe requirements
```
You: "I need to build a user authentication system"
```
### 2. AI creates structured documents
```
AI: "I'll help you create spec workflow for user authentication..."
📝 requirements.md - User stories and functional requirements
🎨 design.md - Technical architecture and design decisions
✅ tasks.md - Concrete implementation task list
```
### 3. Review and implement step by step
After each stage, the AI requests your confirmation before proceeding, ensuring the project stays on the right track.
## Document Organization
### Basic Structure
```
my-project/specs/
├── requirements.md # Requirements: user stories, functional specs
├── design.md # Design: architecture, APIs, data models
├── tasks.md # Tasks: numbered implementation steps
└── .workflow-confirmations.json # Status: automatic progress tracking
```
### Multi-module Projects
```
my-project/specs/
├── user-authentication/ # Auth module
├── payment-system/ # Payment module
└── notification-service/ # Notification module
```
You can specify any directory: `"Use spec workflow to create auth docs in ./src/features/auth"`
## AI Usage Guide
### 🤖 Make AI Use This Tool Better
**Strongly recommended** to add the following prompt to your AI assistant configuration. Without it, AI may:
- ❌ Not know when to invoke Spec Workflow
- ❌ Forget to manage task progress, causing disorganized work
- ❌ Not utilize Spec Workflow for systematic documentation
- ❌ Unable to continuously track project status
With this configuration, AI will intelligently use Spec Workflow to manage the entire development process.
> **Configuration Note**: Please modify the following based on your needs:
> 1. Change `./specs` to your preferred documentation directory path
> 2. Change "English" to your preferred documentation language (e.g., "Chinese")
```
# Spec Workflow Usage Guidelines
## 1. Check Project Progress
When user mentions continuing previous project or is unsure about current progress, proactively use:
specs-workflow tool with action.type="check" and path="./specs"
## 2. Documentation Language
All spec workflow documents should be written in English consistently, including all content in requirements, design, and task documents.
## 3. Documentation Directory
All spec workflow documents should be placed in ./specs directory to maintain consistent project documentation organization.
## 4. Task Management
Always use the following to manage task progress:
specs-workflow tool with action.type="complete_task" and taskNumber="current task number"
Follow the workflow guidance to continue working until all tasks are completed.
## 5. Best Practices
- Proactive progress check: When user says "continue from last time", first use check to see current status
- Language consistency: Use the same language throughout all project documents
- Flexible structure: Choose single-module or multi-module organization based on project scale
- Task granularity: Each task should be completable within 1-2 hours
```
## Installation
<details>
<summary>📦 Installation Instructions</summary>
### Requirements
- Node.js ≥ v18.0.0
- npm or yarn
- Claude Desktop or any MCP-compatible client
### Install in Different MCP Clients
#### Claude Code (Recommended)
Use the Claude CLI to add the MCP server:
```bash
claude mcp add spec-workflow-mcp -s user -- npx -y spec-workflow-mcp@latest
```
#### Claude Desktop
Add to your Claude Desktop configuration:
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%/Claude/claude_desktop_config.json`
- Linux: `~/.config/Claude/claude_desktop_config.json`
```json
{
"mcpServers": {
"spec-workflow": {
"command": "npx",
"args": ["-y", "spec-workflow-mcp@latest"]
}
}
}
```
#### Cursor
Add to your Cursor configuration (`~/.cursor/config.json`):
```json
{
"mcpServers": {
"spec-workflow": {
"command": "npx",
"args": ["-y", "spec-workflow-mcp@latest"]
}
}
}
```
#### Cline
Use Cline's MCP server management UI to add the server:
1. Open VS Code with Cline extension
2. Open Cline settings (gear icon)
3. Navigate to MCP Servers section
4. Add new server with:
- Command: `npx`
- Arguments: `-y spec-workflow-mcp@latest`
#### Windsurf (Codeium)
Add to your Windsurf configuration (`~/.codeium/windsurf/mcp_config.json`):
```json
{
"mcpServers": {
"spec-workflow": {
"command": "npx",
"args": ["-y", "spec-workflow-mcp@latest"],
"env": {},
"autoApprove": [],
"disabled": false,
"timeout": 60,
"transportType": "stdio"
}
}
}
```
#### VS Code (with MCP extension)
Add to your VS Code settings (`settings.json`):
```json
{
"mcp.servers": {
"spec-workflow": {
"command": "npx",
"args": ["-y", "spec-workflow-mcp@latest"]
}
}
}
```
#### Zed
Add to your Zed configuration (`~/.config/zed/settings.json`):
```json
{
"assistant": {
"version": "2",
"mcp": {
"servers": {
"spec-workflow": {
"command": "npx",
"args": ["-y", "spec-workflow-mcp@latest"]
}
}
}
}
}
```
### Install from Source
```bash
git clone https://github.com/kingkongshot/specs-mcp.git
cd specs-mcp
npm install
npm run build
```
Then add to Claude Desktop configuration:
```json
{
"mcpServers": {
"spec-workflow": {
"command": "node",
"args": ["/absolute/path/to/specs-mcp/dist/index.js"]
}
}
}
```
</details>
## Links
- [GitHub Repository](https://github.com/kingkongshot/specs-mcp)
- [NPM Package](https://www.npmjs.com/package/spec-workflow-mcp)
- [Report Issues](https://github.com/kingkongshot/specs-mcp/issues)
## License
MIT License
---
<a href="https://glama.ai/mcp/servers/@kingkongshot/specs-workflow-mcp">
<img width="380" height="200" src="https://glama.ai/mcp/servers/@kingkongshot/specs-workflow-mcp/badge" alt="Spec Workflow MCP server" />
</a>
