@ripla/godd-mcp 0.1.2-beta-20260312091403

package/README.md

@@ -0,0 +1,412 @@
+# GoDD MCP Server
+
+**GoDD（Governance-orchestrated Driven Development / 統治駆動開発）** の方法論を、Cursor IDE のチャット AI に注入する MCP サーバーです。
+追加の API キーは不要です。Cursor 搭載の AI がそのまま処理します。
+
+---
+
+## 必要なもの
+
+| 項目 | 備考 |
+|------|------|
+| Cursor IDE | 最新版推奨 |
+| ライセンスキー | 管理者から受領 |
+| Registry URL | 管理者から受領 |
+
+Node.js のインストールは不要です。
+
+---
+
+## セットアップ
+
+### Step 1: GoDD をインストールする
+
+ZIP を展開したフォルダで以下を実行してください。
+
+**Windows:**
+
+```
+.\godd.exe install
+```
+
+**macOS / Linux:**
+
+```bash
+chmod +x godd
+./godd install
+```
+
+> macOS で「開発元不明」の警告が出た場合は、先に以下を実行してください:
+>
+> ```bash
+> xattr -d com.apple.quarantine godd
+> ```
+
+実行すると、`godd` コマンドがシステムに登録されます。
+
+**インストール後、ターミナルを再起動してください。**
+
+正しくインストールされたか確認するには:
+
+```
+godd version
+```
+
+バージョンが表示されれば OK です。ZIP フォルダはもう不要なので削除して構いません。
+
+---
+
+### Step 2: プロジェクトをセットアップする
+
+GoDD を使いたいプロジェクトのディレクトリに移動し、`godd init` を実行します。
+
+```bash
+cd /path/to/your-project
+godd init
+```
+
+対話形式で以下を入力していきます:
+
+1. **ライセンスキー** — 管理者から受領したキーを入力
+2. **言語** — `ja`（日本語）など
+3. **Registry URL** — 管理者から指定された URL を入力
+4. **技術スタック** — 使用する言語・フレームワーク・DB を選択
+
+```
+ライセンスキーを入力してください: godd-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
+使用言語を選択 [ja/en/zh/ru/kz/tr] (default: ja): ja
+Registry API URL (default: http://localhost:8100): https://godd-registry.example.com
+
+【言語】
+  1. Python
+  2. TypeScript
+  3. JavaScript
+  ...
+  選択 (例: 1,2): 1,2
+
+【フロントエンド】
+  1. React
+  2. Next.js
+  ...
+  選択 (例: 1): 1
+
+【バックエンド】
+  1. FastAPI
+  2. Django
+  ...
+  選択 (例: 1): 1
+```
+
+完了すると、以下の 2 ファイルが自動生成されます:
+
+| ファイル | 内容 |
+|---------|------|
+| `config.yaml` | ライセンスキー・技術スタック・言語の設定 |
+| `.cursor/mcp.json` | Cursor IDE への MCP サーバー登録 |
+
+> **config.yaml にはライセンスキーが含まれます。`.gitignore` に追加してください。**
+>
+> ```gitignore
+> config.yaml
+> ```
+
+---
+
+### Step 3: Cursor IDE を再起動する
+
+設定後、Cursor IDE を再起動してください。
+
+再起動後、Settings > MCP で `godd` サーバーのステータスが **Running** になっていれば完了です。
+
+---
+
+### 複数プロジェクトで使う場合
+
+プロジェクトごとに `godd init` を実行するだけです。プロジェクト A は React + FastAPI、プロジェクト B は Vue + Django のように、それぞれ異なる構成にできます。GoDD の再インストールは不要です。
+
+### 技術スタックを変更したい場合
+
+プロジェクトディレクトリで `godd init` を再実行するか、`config.yaml` を直接編集してください。変更後は Cursor IDE を再起動してください。
+
+---
+
+## 利用可能なツール（28 件）
+
+Cursor のチャットで以下のツールが使えます。ツール名を指定しなくても、AI が自動的に適切なツールを選択します。
+全ツールの入力は optional — 引数なしで呼び出し可能で、Chat の文脈から AI が自動補完します。
+
+### プライマリコマンド（厳選 6 個）
+
+開発の基本ワークフローに必須のコマンド。
+
+| ツール | 説明 | 呼び出し例 |
+|--------|------|-----------|
+| `godd_dev` | 開発ワークフローのメインエントリ。Spec 確認→影響調査→実装→品質ゲート→PR 本文生成まで一貫実行。デフォルトブランチ上では `feat/<slug>-<YYYYMMDD>` ブランチを自動作成 | 「ユーザー登録 API を実装して」 |
+| `godd_review` | CTO レベルのコードレビュー。アーキテクチャ一貫性・スケーラビリティ・技術的負債・ビジネスインパクトの観点でフィードバック。重大度分類（CRITICAL/MAJOR/MINOR/SUGGESTION）付き | 「この PR をレビューして」 |
+| `godd_check` | 品質チェック。Spec 整合・影響範囲・テスト計画・互換性・セキュリティの観点で提出前チェック | 「品質チェックして」 |
+| `godd_commit` | 責務単位コミット。1 コミット = 1 責務で分割し、Conventional Commits 準拠のメッセージで実行 | 「コミットして」 |
+| `godd_submit` | 提出一括実行。品質チェック → push → PR 作成を一括実行 | 「PR 出して」 |
+| `godd_notes_deploy` | ripla Notes のデプロイ案内（Docker Compose / クラウド / 手動） | 「Notes をデプロイして」 |
+
+### サブコマンド — Git 系
+
+| ツール | 説明 |
+|--------|------|
+| `godd_sync` | main ブランチの最新を取り込み。コンフリクトは SSOT 準拠側を優先 |
+| `godd_new_branch` | 変更を退避し、最新 main からブランチ作成して復元 |
+| `godd_git_workflow` | sync → new-branch → commit を一括実行 |
+| `godd_push` | 提出前チェック。品質ゲート・Spec 整合・機密情報チェック |
+| `godd_push_execute` | 提出前チェック後に git push 実行 |
+| `godd_pr_create` | 変更分析と PR テンプレート準拠の本文生成、GitHub 上で PR 作成 |
+
+### サブコマンド — 設計・仕様系
+
+| ツール | 説明 |
+|--------|------|
+| `godd_spec` | 要求を仕様に変換。API/UI/DB/Feature/Usecase の粒度で Spec 化 |
+| `godd_impact` | 影響分析。変更の影響範囲を洗い出し |
+| `godd_test_plan` | テスト計画。unit/integration/e2e の必要性とテスト項目を策定 |
+| `godd_adr` | ADR 作成。設計判断をトレードオフ・ロールバック含めて記録 |
+
+### サブコマンド — ドキュメント系
+
+| ツール | 説明 |
+|--------|------|
+| `godd_documentation` | ドキュメント更新。Spec/README/設定説明/技術スタックの更新を洗い出し |
+| `godd_docs_init` | docs/ フォルダ構造をテンプレートから生成 |
+| `godd_docs_update` | コード変更に合わせて docs/ 内の関連ドキュメントを同期・更新 |
+| `godd_release_notes` | リリースノート作成。変更点・互換性・既知の問題を整理 |
+
+### サブコマンド — 分析・変換系
+
+| ツール | 説明 |
+|--------|------|
+| `godd_pr_analyze` | PR 分析。差分からレビュー観点・リスク・追加情報を整理 |
+| `godd_report` | 完了報告。変更概要・影響範囲・検証結果・残リスクを整理 |
+| `godd_req_to_flow` | 要求 → ビジネスフロー変換 |
+| `godd_req_to_tickets` | 要求 → チケット分解 |
+| `godd_spec_to_tickets` | 仕様 → チケット変換 |
+
+### サブコマンド — 環境・セットアップ系
+
+| ツール | 説明 |
+|--------|------|
+| `godd_setup` | 環境構築。config.yaml / .cursor/mcp.json 生成、依存導入 |
+| `godd_install` | ツール/MCP サーバーインストール案内 |
+| `godd_dev_workflow` | 開発ワークフロー全体。環境構築→実装→テスト→コミット→PR |
+
+---
+
+## @メンションの使い方
+
+GoDD の MCP ツールやエコシステムツールは、Cursor のチャットで **`@` メンション** して明示的に指定できます。
+
+### メンションの方法
+
+Cursor のチャット入力欄で `@` を入力すると、候補一覧が表示されます。
+
+- **MCP ツール**（`godd_dev` 等）→ 「Tools」カテゴリに表示
+- **エコシステムツール**（`Orval` 等）→ 「MCP Resources」カテゴリに表示
+
+キーワードを続けて入力すると候補が絞り込まれます。候補をクリックまたは Enter で選択すると、チャットにメンションが挿入されます。
+
+### MCP ツールの @メンション
+
+MCP ツールをメンションすると、AI にそのツールの使用を明示的に指示できます。
+
+**構文**: `@godd_dev`（`@` + ツール名）
+
+```
+例 1: ツールを明示して依頼
+
+  @godd_dev ユーザー登録 API を実装して
+
+例 2: 複数ツールの組み合わせ
+
+  @godd_spec この要件を仕様に変換して。
+  完了したら @godd_dev で実装して
+
+例 3: 特定ツールの指定がないと、AI が自動選択
+
+  コミットメッセージを作って
+  → AI が自動的に godd_commit を選択
+```
+
+> **ヒント**: ツール名を指定しなくても AI が自動的に最適なツールを選びます。明示的に指定したい場合にのみ `@` メンションを使ってください。
+
+#### メンション可能な MCP ツール一覧（28 件）
+
+| メンション | 用途 |
+|-----------|------|
+| `@godd_dev` | 開発ワークフロー（ブランチ自動管理・分割コミット付き） |
+| `@godd_review` | CTO レベルコードレビュー |
+| `@godd_check` | 品質チェック |
+| `@godd_commit` | 責務分割コミット |
+| `@godd_submit` | 提出一括実行（品質チェック→push→PR 作成） |
+| `@godd_notes_deploy` | Notes デプロイ案内 |
+| `@godd_sync` | デフォルトブランチ同期 |
+| `@godd_new_branch` | ブランチ作成 |
+| `@godd_git_workflow` | sync→branch→commit 一括 |
+| `@godd_push` | 提出前チェック |
+| `@godd_push_execute` | 提出前チェック＋push 実行 |
+| `@godd_pr_create` | PR 作成 |
+| `@godd_spec` | 要求→仕様変換 |
+| `@godd_impact` | 影響分析 |
+| `@godd_test_plan` | テスト計画作成 |
+| `@godd_adr` | ADR（設計判断記録）作成 |
+| `@godd_documentation` | ドキュメント更新支援 |
+| `@godd_docs_init` | docs/ フォルダ構造生成 |
+| `@godd_docs_update` | docs/ ドキュメント同期 |
+| `@godd_release_notes` | リリースノート作成 |
+| `@godd_pr_analyze` | PR 分析 |
+| `@godd_report` | 完了報告作成 |
+| `@godd_req_to_flow` | 要求→ビジネスフロー変換 |
+| `@godd_req_to_tickets` | 要求→チケット変換 |
+| `@godd_spec_to_tickets` | 仕様→チケット変換 |
+| `@godd_setup` | 環境構築・設定変更 |
+| `@godd_install` | ツール・ライブラリのインストール支援 |
+| `@godd_dev_workflow` | エージェント開発ワークフロー全体 |
+
+### エコシステムツールの @メンション
+
+`godd init` で選択した技術スタックに応じて、プロジェクトで使用するライブラリやフレームワーク（**エコシステムツール**）が MCP リソースとして自動登録されます。これらもチャットで `@` メンションできます。
+
+メンションすると、そのツール固有の **利用ガイダンス**（ベストプラクティス・コマンド例など）が AI のコンテキストに注入され、ツールに適した正確なアドバイスが得られます。
+
+**構文**: `@` → 候補リストから「MCP Resources」セクションのツール名を選択
+
+```
+例 1: 特定ツールのベストプラクティスに沿った実装依頼
+
+  @Orval を使って API クライアントを再生成して
+
+例 2: ツール固有のガイダンスを活用
+
+  @Alembic でマイグレーションを作って。モデルに email カラムを追加した
+
+例 3: 複数のエコシステムツールを組み合わせ
+
+  @TanStack Query と @Orval を使って、
+  ユーザー一覧の取得を実装して
+
+例 4: MCP ツール + エコシステムツールの組み合わせ
+
+  @godd_dev @Playwright でログインフローの E2E テストを書いて
+```
+
+#### エコシステムツールの例（FastAPI + React 構成の場合）
+
+| カテゴリ | ツール | 説明 |
+|---------|--------|------|
+| Frontend | Orval | OpenAPI クライアントコード自動生成 |
+| Frontend | TanStack Query | 非同期データフェッチング/キャッシュ管理 |
+| Frontend | Vite | 高速フロントエンドビルドツール |
+| Frontend | Storybook | UI コンポーネント開発/カタログ |
+| Backend | SQLModel | SQLAlchemy + Pydantic ORM |
+| Backend | Alembic | DB マイグレーション |
+| Backend | FastAPI Users | 認証/ユーザー管理 |
+| DevTool | Ruff | Python Linter / Formatter |
+| DevTool | uv | Python パッケージマネージャ |
+| DevTool | Biome | Linter / Formatter（JS/TS） |
+| Testing | Pytest | Python テストフレームワーク |
+| Testing | HTTPX | Python HTTP クライアント（テスト用） |
+| Testing | Playwright | E2E テストフレームワーク |
+| Infra | Docker Compose | マルチコンテナオーケストレーション |
+| Monitoring | Sentry | エラー追跡 / パフォーマンス監視 |
+
+> **注**: 表示されるエコシステムツールは、`godd init` で選択した技術スタック（コンポーネント）によって変わります。
+
+### 自動 vs 手動
+
+| モード | 動作 | いつ使う |
+|--------|------|---------|
+| **自動** | ツール名を指定せず依頼すると、AI が最適な MCP ツールを自動選択。エコシステムツールのガイダンスもスタック設定に基づいて自動注入される | 通常の開発作業 |
+| **手動** | `@` で MCP ツールやエコシステムツールを明示指定 | 特定のツールを確実に使いたい場合、複数ツールを組み合わせたい場合 |
+
+---
+
+## トラブルシューティング
+
+### `godd` コマンドが見つからない
+
+`godd install` を再実行し、ターミナルを再起動してください。
+
+### MCP サーバーが起動しない
+
+1. `godd version` が動くか確認
+2. `config.yaml` がプロジェクトルートにあるか確認
+3. `.cursor/mcp.json` が存在するか確認
+4. 手動でサーバーを起動してエラーを確認:
+
+**Windows:**
+
+```
+set GODD_CONFIG=C:\path\to\your-project\config.yaml
+godd server
+```
+
+**macOS / Linux:**
+
+```bash
+GODD_CONFIG=/path/to/your-project/config.yaml godd server
+```
+
+### ライセンスエラー
+
+| エラー | 対処 |
+|--------|------|
+| `Invalid license key` | `config.yaml` のライセンスキーが正しいか確認 |
+| `License has expired` | 管理者に更新を依頼 |
+| `Seat limit reached` | 管理者にシート解放を依頼 |
+
+### Registry に接続できない
+
+- `config.yaml` の `registry_url` が正しいか確認
+- ネットワーク接続を確認
+
+初回接続後は 10 時間のローカルキャッシュが有効です。キャッシュ期間中はオフラインでも動作します。
+
+---
+
+## リリース（npm publish）
+
+`main` ブランチに `godd-mcp-server/` 配下の変更がマージされると、GitHub Actions が自動で npm publish を実行します。
+
+### バージョン自動判定ルール
+
+コミットメッセージを [Conventional Commits](https://www.conventionalcommits.org/) のプレフィックスで解析し、semver のどの桁を上げるかを自動判定します。
+
+| バンプ | 条件 | 例 |
+|--------|------|-----|
+| **MAJOR** (X.0.0) | `BREAKING CHANGE` を含む、または `feat!:` / `fix!:` 等の `!` 付きプレフィックス | `feat!: remove legacy stack_profile mode` |
+| **MINOR** (0.X.0) | `feat` プレフィックス | `feat(scanner): add Terraform detection` |
+| **PATCH** (0.0.X) | 上記以外（`fix`, `docs`, `chore`, `refactor`, `test` 等） | `fix: correct template path resolution` |
+
+### 前提条件
+
+GitHub リポジトリの **Settings > Secrets and variables > Actions** に以下を設定:
+
+| Secret 名 | 値 |
+|------------|-----|
+| `NPM_TOKEN` | npmjs.com のアクセストークン（Automation タイプ推奨） |
+
+### 手動でバージョンを確認する
+
+```bash
+cd godd-mcp-server
+node scripts/bump-version.mjs --dry
+```
+
+---
+
+## GoDD CLI コマンド一覧
+
+| コマンド | 短縮形 | 説明 |
+|---------|--------|------|
+| `godd server` | `godd s` | MCP サーバーを起動（Cursor が自動実行） |
+| `godd init` | — | プロジェクトのセットアップ（config.yaml + .cursor/mcp.json 生成） |
+| `godd install` | `godd i` | GoDD をシステムにインストール |
+| `godd notes deploy` | `godd n deploy` | ripla Notes を Docker Compose でデプロイ |
+| `godd notes infra` | `godd n infra` | クラウドインフラを対話形式で構築（AWS/GCP/Azure/Vercel×Railway） |
+| `godd version` | `godd v` | バージョン表示 |
+| `godd help` | `godd h` | ヘルプ表示 |