# OpenSpec MCP
[](https://www.npmjs.com/package/openspec-mcp)
MCP (Model Context Protocol) server for [OpenSpec](https://github.com/Fission-AI/OpenSpec) - spec-driven development with real-time dashboard and approval workflow.
## Features
- **MCP Tools**: Full OpenSpec CLI functionality exposed as MCP tools
- **Review System**: Add, reply, resolve review comments on proposals/designs
- **Task Tracking**: Parse tasks.md and track progress in real-time
- **Approval Workflow**: Request, approve, and reject change proposals
- **Cross-Service Docs**: View cross-service design documents from single service projects
- **Web Dashboard**: Visual management interface with real-time updates and Markdown rendering
## Quick Start
### 1. Add to your MCP configuration
**Claude Code CLI (recommended - uses current directory):**
```bash
claude mcp add openspec -- npx openspec-mcp
```
**Claude Code CLI with Dashboard:**
```bash
claude mcp add openspec -- npx openspec-mcp --with-dashboard
```
**Claude Code CLI with specific project path:**
```bash
claude mcp add openspec -- npx openspec-mcp /path/to/your/project
```
**Claude Desktop / Cursor / Other:**
```json
{
"mcpServers": {
"openspec": {
"command": "npx",
"args": ["-y", "openspec-mcp"]
}
}
}
```
**With Dashboard:**
```json
{
"mcpServers": {
"openspec": {
"command": "npx",
"args": ["-y", "openspec-mcp", "--with-dashboard"]
}
}
}
```
### 2. Use in conversation
```
# List all changes
"List all openspec changes"
# Show change details
"Show me the add-user-auth change"
# Update task status
"Mark task 1.1 as done in add-user-auth"
# Request approval
"Request approval for add-user-auth from @reviewer"
```
## Available Prompts (New!)
Directly leverage your Client's AI capabilities (Claude, Codex) with context-aware prompts.
| Prompt | Description |
| ----------------- | ----------------------------------------------- |
| `analyze-project` | Deep analysis of project architecture and stack |
| `review-change` | Intelligent review of changes with linked specs |
## Available Tools
### Guides & Context
| Tool | Description |
| ------------------------------ | --------------------------------- |
| `openspec_get_instructions` | Get AGENTS.md usage guide |
| `openspec_get_project_context` | Get project.md context |
| `openspec_analyze_context` | Analyze project structure & stack |
| `openspec_ai_analyze_context` | AI-enhanced context analysis |
### Management
| Tool | Description |
| ----------------------- | ------------------------- |
| `openspec_list_changes` | List all change proposals |
| `openspec_list_specs` | List all specifications |
| `openspec_show_change` | Show change details |
| `openspec_show_spec` | Show spec details |
### Validation
| Tool | Description |
| -------------------------- | ----------------- |
| `openspec_validate_change` | Validate a change |
| `openspec_validate_spec` | Validate a spec |
| `openspec_validate_all` | Batch validation |
### Archive
| Tool | Description |
| ------------------------- | ------------------------ |
| `openspec_archive_change` | Archive completed change |
### Tasks
| Tool | Description |
| ------------------------------- | ------------------------ |
| `openspec_get_tasks` | Get tasks and progress |
| `openspec_update_task` | Update task status |
| `openspec_batch_update_tasks` | Batch update task status |
| `openspec_get_progress_summary` | Get all changes progress |
### Approval
| Tool | Description |
| --------------------------------- | ---------------------- |
| `openspec_get_approval_status` | Get approval status |
| `openspec_request_approval` | Request approval |
| `openspec_approve_change` | Approve a change |
| `openspec_reject_change` | Reject a change |
| `openspec_list_pending_approvals` | List pending approvals |
### Reviews
| Tool | Description |
| ----------------------------- | ------------------------------------------- |
| `openspec_add_review` | Add review comment to proposal/design/tasks |
| `openspec_list_reviews` | List reviews with filters |
| `openspec_reply_review` | Reply to a review |
| `openspec_resolve_review` | Mark review as resolved |
| `openspec_get_review_summary` | Get review statistics & blocking issues |
### Templates
| Tool | Description |
| --------------------------- | --------------------------- |
| `openspec_list_templates` | List available templates |
| `openspec_create_change` | Create change from template |
| `openspec_preview_template` | Preview template content |
### Generator
| Tool | Description |
| ---------------------------- | ----------------------------------- |
| `openspec_generate_proposal` | Generate proposal from requirements |
| `openspec_save_proposal` | Save generated proposal |
### Hooks
| Tool | Description |
| ---------------------- | --------------------------- |
| `openspec_setup_hooks` | Setup git hooks for project |
### Cross-Service
| Tool | Description |
| ---------------------------------- | ----------------------------- |
| `openspec_list_cross_service_docs` | List cross-service documents |
| `openspec_read_cross_service_doc` | Read a cross-service document |
## Cross-Service Documentation
For multi-service projects sharing a common `.cross-service/` directory (e.g., in a Git worktree), configure your `proposal.md` frontmatter:
```yaml
---
crossService:
rootPath: "../../../../.cross-service" # Relative to change directory
documents:
- design.md
- flows.md
- services.yaml
archivePolicy: snapshot # 'snapshot' (default) or 'reference'
---
# Your proposal content...
```
The Dashboard will display a "Cross-Service" tab with:
- **design.md / flows.md**: Rendered as Markdown
- **services.yaml**: Visual card view with service status, changes, and deployment order
## Approval Workflow
```
draft -> pending_approval -> approved -> implementing -> completed -> archived
-> rejected -> draft (revise and resubmit)
```
Approval records are stored in `openspec/approvals/<change-id>.json`.
## CLI Options
```bash
openspec-mcp [path] [options]
Arguments:
path Project directory path (default: current directory)
Options:
--dashboard Start web dashboard only (HTTP mode)
--with-dashboard Start MCP server with web dashboard
-p, --port <number> Dashboard port (default: 3000; auto-increments if busy, 0 for random)
-V, --version Output version number
-h, --help Display help
```
### Examples
```bash
# MCP server only (uses current directory)
openspec-mcp
# MCP server with specific project
openspec-mcp /path/to/project
# Dashboard only
openspec-mcp --dashboard
# MCP server + Dashboard
openspec-mcp --with-dashboard
# Dashboard on custom port
openspec-mcp --dashboard --port 8080
```
## Web Dashboard
The dashboard provides a visual interface for managing changes, tracking tasks, and handling approvals.
### Dashboard Pages
| Route | Description |
| -------------- | -------------------------------------- |
| `/` | Overview with stats and recent changes |
| `/kanban` | Drag-and-drop Kanban board |
| `/changes` | List all changes with progress |
| `/changes/:id` | Change detail with Specs & Tasks |
| `/qa` | QA Runner dashboard |
| `/context` | Project analysis & Tech stack |
| `/specs` | Browse specifications |
| `/approvals` | Approval queue management |
### Features
- **Real-time Updates**: WebSocket connection for live progress and review updates
- **Kanban Board**: 6-column workflow (Backlog -> Released) with drag-and-drop support
- **QA Dashboard**: Monitor and trigger quality checks directly from UI
- **Context Analysis**: Auto-detect tech stack and visualize directory structure
- **Task Management**: Toggle task status directly from the UI
- **Approval Actions**: Approve/reject changes with comments
- **Progress Visualization**: Progress bars and status badges
- **Review Management**: View, resolve and track reviews with Open/Resolved tabs
- **Cross-Service Docs**: View cross-service design documents with visual services.yaml display
- **Markdown Rendering**: Proposals and designs rendered with full Markdown support
## Development
```bash
# Install dependencies
npm install
# Build
npm run build
# Development mode
npm run dev
# Run tests
npm test
```
## Requirements
- Node.js >= 20.0.0
- OpenSpec CLI (`npm install -g @fission-ai/openspec`)
## License
MIT
