# 🛠️ Spec-Kit Plus MCP Server

MCP (Model Context Protocol) server that wraps Spec-Kit Plus tools so any AI IDE or CLI (Qwen, Gemini, Claude Code, Cursor, etc.) can use it globally.

## 📦 What This Is

This MCP server acts as a bridge between AI agents and the Spec-Kit Plus CLI (`specifyplus`), enabling spec-driven development workflows across any MCP-compatible AI tool.

```
User (in any AI IDE/CLI)
        │
        ▼
   MCP Protocol
        │
        ▼
  speckit-plus-mcp/
    server.py          ← MCP Server
        │
        ▼
  specifyplus CLI      ← Spec-Kit Plus (sp init, sp.plan, sp.tasks, etc.)
```

## ✅ Prerequisites

```bash
# Install specifyplus (the CLI being wrapped)
pip install specifyplus

# Install MCP Python SDK
pip install "mcp[cli]"
```

## 🚀 Installation

1. **Clone or download this repository**

2. **Install dependencies:**
   ```bash
   cd speckit-plus-mcp
   pip install -e .
   ```

3. **Configure your AI agent** (see below)

## 🔧 Configuration

### Qwen CLI

Create `~/.qwen/settings.json`:

```json
{
  "mcpServers": {
    "speckit-plus": {
      "command": "python",
      "args": ["/ABSOLUTE/PATH/TO/speckit-plus-mcp/server.py"],
      "env": {
        "PYTHONPATH": "."
      }
    }
  }
}
```

> ⚠️ Replace `/ABSOLUTE/PATH/TO/` with your actual path.

### Gemini CLI

Create `~/.gemini/settings.json`:

```json
{
  "mcpServers": {
    "speckit-plus": {
      "command": "python",
      "args": ["/ABSOLUTE/PATH/TO/speckit-plus-mcp/server.py"]
    }
  }
}
```

### Claude Code

Create `~/.claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "speckit-plus": {
      "command": "python",
      "args": ["/ABSOLUTE/PATH/TO/speckit-plus-mcp/server.py"]
    }
  }
}
```

### Cursor / VS Code (with MCP extension)

Add to `.cursor/mcp.json` inside your project:

```json
{
  "mcpServers": {
    "speckit-plus": {
      "command": "python",
      "args": ["/ABSOLUTE/PATH/TO/speckit-plus-mcp/server.py"]
    }
  }
}
```

## 🧪 Testing

### Test the server runs correctly:

```bash
cd speckit-plus-mcp
python server.py
```

You should see: `Running MCP server 'speckit-plus'`

### Test inside Qwen CLI:

```bash
qwen
```

Then type `/mcp` — you should see:

```
speckit-plus: CONNECTED
Tools: speckit_init, speckit_check, speckit_specify, speckit_plan ...
```

## 📋 Available Tools

| Tool | Description |
|------|-------------|
| `speckit_init` | Initialize a new Spec-Kit Plus project for any AI agent |
| `speckit_check` | Verify all required tools are installed |
| `speckit_constitution` | Set project governing principles |
| `speckit_specify` | Write requirements specification (WHAT to build) |
| `speckit_clarify` | Run structured clarification before planning |
| `speckit_plan` | Generate technical plan with tech stack (HOW to build) |
| `speckit_tasks` | Break plan into ordered task list |
| `speckit_implement` | Execute all tasks to build the full project |
| `speckit_workflow_guide` | Get complete step-by-step workflow instructions |

## 📘 Usage Example

### In your AI agent (Qwen, Claude, etc.):

```
Use speckit_init to create a project called "todo-app" for qwen,
then show me the workflow guide.
```

### Complete Workflow:

1. **Initialize project:**
   ```
   speckit_init(project_name="my-app", ai_agent="qwen")
   ```

2. **Set principles:**
   ```
   /sp.constitution Enforce clean code, testing, and performance
   ```

3. **Write specification:**
   ```
   /sp.specify Build a task manager with Kanban boards and user assignments
   ```

4. **Clarify gaps (recommended):**
   ```
   /sp.clarify
   ```

5. **Technical plan:**
   ```
   /sp.plan Use FastAPI, PostgreSQL, React, Docker
   ```

6. **Generate tasks:**
   ```
   /sp.tasks
   ```

7. **Build the project:**
   ```
   /sp.implement
   ```

## 🎯 Supported AI Agents

- qwen
- claude
- gemini
- copilot
- cursor
- windsurf
- opencode
- codex
- amp

## 📁 Output Files

After running the workflow, you'll find these files in `.specify/`:

```
.specify/
├── memory/
│   └── constitution.md    ← Your project principles
└── specs/
    └── 001-feature/
        ├── spec.md        ← Requirements & user stories
        ├── plan.md        ← Technical implementation plan
        ├── tasks.md       ← Ordered task list
        └── data-model.md  ← Database schema
```

## 🏗️ How It Works

```
AI Agent (Qwen/Gemini/Claude)
        │
        │  speaks MCP protocol
        ▼
   server.py  (MCP server)
        │
        │  calls subprocess
        ▼
   specifyplus CLI  (sp commands)
        │
        │  reads/writes
        ▼
   .specify/ folder
   (spec.md, plan.md, tasks.md)
        │
        │  used by
        ▼
   AI Agent builds the project
```

**MCP = Model Context Protocol** — a standard that lets any AI agent talk to any tool server. This `server.py` IS the bridge between the AI and Spec-Kit Plus.

## 📄 License

MIT
