# Spec Workflow MCP

[![npm version](https://img.shields.io/npm/v/@arimakouyou/spec-workflow-mcp)](https://www.npmjs.com/package/@arimakouyou/spec-workflow-mcp)
[![VSCode Extension](https://vsmarketplacebadges.dev/version-short/arimakouyou.spec-workflow-mcp.svg)](https://marketplace.visualstudio.com/items?itemName=arimakouyou.spec-workflow-mcp)

リアルタイムダッシュボードとVSCode拡張機能を備えた、構造化された仕様駆動開発のためのModel Context Protocol (MCP) サーバーです。

## ☕ このプロジェクトを支援する

<a href="https://buymeacoffee.com/arimakouyou" target="_blank"><img src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png" alt="Buy Me A Coffee" style="height: 60px !important;width: 217px !important;" ></a>

## 📺 ショーケース

### 🔄 承認システムの動作

<a href="https://www.youtube.com/watch?v=C-uEa3mfxd0" target="_blank">
  <img src="https://img.youtube.com/vi/C-uEa3mfxd0/maxresdefault.jpg" alt="Approval System Demo" width="600">
</a>

*承認システムの動作をご覧ください：ドキュメント作成、ダッシュボードでの承認リクエスト、フィードバック提供、改訂の追跡。*

### 📊 ダッシュボードと仕様管理

<a href="https://www.youtube.com/watch?v=g9qfvjLUWf8" target="_blank">
  <img src="https://img.youtube.com/vi/g9qfvjLUWf8/maxresdefault.jpg" alt="Dashboard Demo" width="600">
</a>

*リアルタイムダッシュボードを探索：仕様の表示、進捗の追跡、ドキュメントのナビゲート、開発ワークフローの監視。*

## ✨ 主な機能

- **構造化された開発ワークフロー** - 順次仕様作成（要求仕様 → 要件 → 設計 → テスト設計 → タスク）
- **リアルタイムWebダッシュボード** - ライブ更新で仕様、タスク、進捗を監視
- **VSCode拡張機能** - VSCodeユーザー向けの統合サイドバーダッシュボード
- **承認ワークフロー** - 改訂を含む完全な承認プロセス
- **タスク進捗追跡** - ビジュアル進捗バーと詳細なステータス
- **実装ログ** - コード統計を含むすべてのタスク実装の検索可能なログ
- **多言語サポート** - 11言語で利用可能

## 🌍 サポート言語

🇺🇸 English • 🇯🇵 日本語 • 🇨🇳 中文 • 🇪🇸 Español • 🇧🇷 Português • 🇩🇪 Deutsch • 🇫🇷 Français • 🇷🇺 Русский • 🇮🇹 Italiano • 🇰🇷 한국어 • 🇸🇦 العربية

## 🚀 クイックスタート

### 方法1: Claude Code プラグイン（Claude Code ユーザーに推奨）

Claude Code プラグインとして直接インストールできます。スキル、エージェント、ルール、フック、MCP サーバーがすべて自動で設定されます：

```bash
claude plugin add --from https://github.com/arimakouyou/spec-workflow-mcp
```

2つのプラグインバリアントが利用可能です：

| プラグイン | 説明 |
|--------|-------------|
| `spec-workflow-mcp` | MCP サーバー + スキル/エージェント/ルール/フック |
| `spec-workflow-mcp-with-dashboard` | MCP サーバーのみ（軽量版、スキル/エージェント/ルール/フックなし） |

> **注意**: `spec-workflow-mcp-with-dashboard` バリアントは MCP サーバーのみを含む最小構成です。ダッシュボードを使用するには、`npx -y @arimakouyou/spec-workflow-mcp@latest --dashboard` で別途起動してください。

> **プラグインに含まれるもの：**
> - 仕様駆動開発ワークフロー用の MCP サーバー
> - スキル：spec-request-spec、spec-requirements、spec-design、spec-test-design、spec-tasks、spec-implement、spec-review、integration-test、TDD など
> - エージェント：code-simplifier、review-worker、unit-test-engineer、parallel-worker など
> - ルール：プロジェクトアーキテクチャ、品質チェック、セキュリティ、設計原則など
> - フック：タスク読み取りガードの自動化

### 方法2: 手動 MCP 設定

MCP設定に追加します（以下のクライアント固有のセットアップを参照）：

```json
{
  "mcpServers": {
    "spec-workflow": {
      "command": "npx",
      "args": ["-y", "@arimakouyou/spec-workflow-mcp@latest", "/path/to/your/project"]
    }
  }
}
```

### ステップ2: インターフェースを選択する

**オプションA: Webダッシュボード**（CLIユーザーに必須）
ダッシュボードを起動します（デフォルトポート5000で実行）：
```bash
npx -y @arimakouyou/spec-workflow-mcp@latest --dashboard
```

ダッシュボードは以下のURLでアクセス可能です：http://localhost:5000

> **注意：** ダッシュボードインスタンスは1つだけ必要です。すべてのプロジェクトが同じダッシュボードに接続します。

**オプションB: VSCode拡張機能**（VSCodeユーザーに推奨）

VSCodeマーケットプレイスから[Spec Workflow MCP Extension](https://marketplace.visualstudio.com/items?itemName=arimakouyou.spec-workflow-mcp)をインストールします。

## 📝 使い方

会話でspec-workflowに言及するだけです：

- **「ユーザー認証の仕様を作成して」** - 完全な仕様ワークフローを作成
- **「仕様一覧を表示して」** - すべての仕様とそのステータスを表示
- **「user-auth仕様のタスク1.2を実行して」** - 特定のタスクを実行

[その他の例を見る →](docs/PROMPTING-GUIDE.ja.md)

## 🔧 MCPクライアントセットアップ

<details>
<summary><strong>Augment Code</strong></summary>

Augment設定で設定します：
```json
{
  "mcpServers": {
    "spec-workflow": {
      "command": "npx",
      "args": ["-y", "@arimakouyou/spec-workflow-mcp@latest", "/path/to/your/project"]
    }
  }
}
```
</details>

<details>
<summary><strong>Claude Code CLI</strong></summary>

MCP設定に追加します：
```bash
claude mcp add spec-workflow npx @arimakouyou/spec-workflow-mcp@latest -- /path/to/your/project
```

**重要な注意事項：**
- `-y`フラグは、スムーズなインストールのためにnpmプロンプトをバイパスします
- `--`区切り文字により、パスがnpxではなくspec-workflowスクリプトに渡されます
- `/path/to/your/project`を実際のプロジェクトディレクトリパスに置き換えてください

**Windows用の代替方法（上記が機能しない場合）：**
```bash
claude mcp add spec-workflow cmd.exe /c "npx @arimakouyou/spec-workflow-mcp@latest /path/to/your/project"
```
</details>

<details>
<summary><strong>Claude Desktop</strong></summary>

`claude_desktop_config.json`に追加します：
```json
{
  "mcpServers": {
    "spec-workflow": {
      "command": "npx",
      "args": ["-y", "@arimakouyou/spec-workflow-mcp@latest", "/path/to/your/project"]
    }
  }
}
```

> **重要：** MCPサーバーを起動する前に、`--dashboard`を使用してダッシュボードを別途実行してください。

</details>

<details>
<summary><strong>Cline/Claude Dev</strong></summary>

MCPサーバー設定に追加します：
```json
{
  "mcpServers": {
    "spec-workflow": {
      "command": "npx",
      "args": ["-y", "@arimakouyou/spec-workflow-mcp@latest", "/path/to/your/project"]
    }
  }
}
```
</details>

<details>
<summary><strong>Continue IDE Extension</strong></summary>

Continue設定に追加します：
```json
{
  "mcpServers": {
    "spec-workflow": {
      "command": "npx",
      "args": ["-y", "@arimakouyou/spec-workflow-mcp@latest", "/path/to/your/project"]
    }
  }
}
```
</details>

<details>
<summary><strong>Cursor IDE</strong></summary>

Cursor設定（`settings.json`）に追加します：
```json
{
  "mcpServers": {
    "spec-workflow": {
      "command": "npx",
      "args": ["-y", "@arimakouyou/spec-workflow-mcp@latest", "/path/to/your/project"]
    }
  }
}
```
</details>

<details>
<summary><strong>OpenCode</strong></summary>

`opencode.json`設定ファイルに追加します：
```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "spec-workflow": {
      "type": "local",
      "command": ["npx", "-y", "@arimakouyou/spec-workflow-mcp@latest", "/path/to/your/project"],
      "enabled": true
    }
  }
}
```
</details>

<details>
<summary><strong>Windsurf</strong></summary>

`~/.codeium/windsurf/mcp_config.json`設定ファイルに追加します：
```json
{
  "mcpServers": {
    "spec-workflow": {
      "command": "npx",
      "args": ["-y", "@arimakouyou/spec-workflow-mcp@latest", "/path/to/your/project"]
    }
  }
}
```
</details>

<details>
<summary><strong>Codex</strong></summary>

`~/.codex/config.toml`設定ファイルに追加します：
```toml
[mcp_servers.spec-workflow]
command = "npx"
args = ["-y", "@arimakouyou/spec-workflow-mcp@latest", "/path/to/your/project"]
```
</details>

## 🐳 Dockerデプロイ

Dockerコンテナでダッシュボードを実行し、分離されたデプロイを実現します：

```bash
# Docker Composeを使用（推奨）
cd containers
docker-compose up --build

# またはDocker CLIを使用
docker build -f containers/Dockerfile -t spec-workflow-mcp .
docker run -p 5000:5000 -v "./workspace/.spec-workflow:/workspace/.spec-workflow:rw" spec-workflow-mcp
```

ダッシュボードは以下のURLで利用可能になります：http://localhost:5000

[Dockerセットアップガイドを見る →](containers/README.md)

## 🔒 サンドボックス環境

`$HOME`が読み取り専用のサンドボックス環境（例：Codex CLIの`sandbox_mode=workspace-write`）の場合、`SPEC_WORKFLOW_HOME`環境変数を使用してグローバル状態ファイルを書き込み可能な場所にリダイレクトします：

```bash
SPEC_WORKFLOW_HOME=/workspace/.spec-workflow-mcp npx -y @arimakouyou/spec-workflow-mcp@latest /workspace
```

[設定ガイドを見る →](docs/CONFIGURATION.ja.md#environment-variables)

## 📚 ドキュメント

- [設定ガイド](docs/CONFIGURATION.ja.md) - コマンドラインオプション、設定ファイル
- [ユーザーガイド](docs/USER-GUIDE.ja.md) - 包括的な使用例
- [ワークフロープロセス](docs/WORKFLOW.ja.md) - 開発ワークフローとベストプラクティス
- [インターフェースガイド](docs/INTERFACES.ja.md) - ダッシュボードとVSCode拡張機能の詳細
- [プロンプティングガイド](docs/PROMPTING-GUIDE.ja.md) - 高度なプロンプティング例
- [ツールリファレンス](docs/TOOLS-REFERENCE.ja.md) - 完全なツールドキュメント
- [開発](docs/DEVELOPMENT.ja.md) - 貢献と開発セットアップ
- [トラブルシューティング](docs/TROUBLESHOOTING.ja.md) - 一般的な問題と解決策

## 📁 プロジェクト構造

### 作業ディレクトリ（プロジェクトごと）

```
your-project/
  .spec-workflow/
    approvals/
    archive/
    specs/
    steering/
    templates/
    user-templates/
    config.example.toml
```

### プラグイン構造（`.claude-plugin/` で配布）

```
.claude-plugin/
  plugin.json              # プラグインマニフェスト
  marketplace.json         # マーケットプレイスリスティング
  .mcp.json                # MCP サーバー設定
  hooks/
    hooks.json             # フック定義（PostToolUse など）
    tasks-read-guard.sh    # タスク読み取りガードスクリプト
  skills/                  # 仕様駆動ワークフロースキル
    spec-requirements/     # 要件作成
    spec-design/           # 設計ドキュメント作成
    spec-test-design/      # テスト設計作成
    spec-tasks/            # タスク分割
    spec-implement/        # 実装ワークフロー
    spec-review/           # コードレビュー
    integration-test/      # 統合テスト
    tdd-skills/            # TDD ワークフロー
    tdd-skills-rust/       # Rust 特化 TDD
    knowhow-capture/       # ナレッジキャプチャ
  agents/                  # 専門サブエージェント
    code-simplifier.md     # コード簡素化
    review-worker.md       # レビュー自動化
    unit-test-engineer.md  # ユニットテスト生成
    parallel-worker.md     # 並列タスク実行
    integ-test-worker.md   # 統合テストワーカー
    integ-test-auditor.md  # 統合テスト監査
  rules/                   # プロジェクトルールと規約
    quality-checks.md      # 品質チェック
    security.md            # セキュリティガイドライン
    design-principles.md   # 設計原則
    ...
  with-dashboard/          # ダッシュボードバリアント
    plugin.json
    .mcp.json
```

## 🛠️ 開発

```bash
# 依存関係をインストール
npm install

# プロジェクトをビルド
npm run build

# 開発モードで実行
npm run dev
```

[開発ガイドを見る →](docs/DEVELOPMENT.ja.md)

## 📄 ライセンス

GPL-3.0

## ⭐ スター履歴

<a href="https://www.star-history.com/#arimakouyou/spec-workflow-mcp&Date">
 <picture>
   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=arimakouyou/spec-workflow-mcp&type=Date&theme=dark" />
   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=arimakouyou/spec-workflow-mcp&type=Date" />
   <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=arimakouyou/spec-workflow-mcp&type=Date" />
 </picture>
</a>
