@autodevjapan/godd-mcp-alpha 1.25.16 → 1.25.18

package/README.md

@@ -1,14 +1,162 @@
 # GoDD MCP α Server
 
+[🇺🇸 English](#english) | [🇯🇵 日本語](#日本語) | [🇷🇺 Русский](#русский)
+
+---
+
+## English
+
+AI prompt delivery system for Cursor IDE. Delivers project-optimized prompts, mindsets, and agent definitions via MCP (Model Context Protocol).
+
+### Installation
+
+```bash
+npm install -g @autodevjapan/godd-mcp-alpha
+```
+
+### Setup (Recommended)
+
+```bash
+# Register the MCP server with Cursor IDE (auto-generates mcp.json)
+godd-a install --license-key=YOUR_LICENSE_KEY
+
+# Auto-generate project config.godd (interactive)
+godd-a init
+
+# Or fully automatic mode (for CI/CD)
+godd-a init --auto
+```
+
+> **Use `godd-a install`.** Manual editing of mcp.json is not recommended.
+> `godd-a install` correctly configures the startup command, PATH, and license key.
+
+### Manual mcp.json Configuration
+
+If `godd-a install` is unavailable, you can edit `~/.cursor/mcp.json` directly.
+**The `serve` argument is required.** Without it, the installer mode starts and MCP communication breaks.
+
+```json
+{
+  "mcpServers": {
+    "godd-a": {
+      "command": "npx",
+      "args": ["-y", "@autodevjapan/godd-mcp-alpha@latest", "serve"],
+      "env": {
+        "GODD_LICENSE_KEY": "GODD-XXXX-XXXX"
+      }
+    }
+  }
+}
+```
+
+### Usage
+
+After installation, restart Cursor IDE and the GoDD MCP α server will start automatically.
+
+In Cursor chat, simply ask the AI to use a specific tool (e.g., "run dev", "do a review"). The AI will automatically discover and invoke the appropriate GoDD tool.
+
+### GoDD Prompts
+
+Available GoDD prompts (MCP tools) in Cursor IDE:
+
+| Prompt | Description |
+|---|---|
+| `dev` | Development (plan → implement → test → quality → docs in stages) |
+| `check` | Quality gate (verify spec alignment, tests, types, lint, security) |
+| `docs` | Generate/update documentation |
+| `ship` | Ship (commit at proper granularity → quality check → push → create PR) |
+| `setup` | Environment setup (with recommended stack presets, confirms missing info) |
+| `review` | Review (CTO-level review + quality gate) |
+| `test` | Run/create tests |
+| `impact` | Impact analysis |
+| `commit` | Commit changes |
+| `push` | Push to remote |
+| `pr` | Create PR (template-compliant) |
+| `deploy` | Deploy (with verification & rollback plan) |
+| `adr` | Create ADR (Architecture Decision Record) |
+| `release` | Generate release notes (SemVer-compliant) |
+| `github` | GitHub configuration (repository/branch protection etc.) |
+| `config` | Generate/repair config.godd (auto-detect stack + validation) |
+| `questions` | Manage question list (質問リスト.md) interactively |
+| `e2e` | Browser-based E2E testing (execute & verify critical user flows) |
+| `map` | Project knowledge graph (visualize architecture & dependencies with Mermaid) |
+| `learn` | Save/recall project-specific patterns, conventions, and pitfalls |
+| `diagram` | Auto-update architecture diagrams (maintain living Mermaid docs in sync with code) |
+| `slide` | Generate presentation slides from project docs (Marp Markdown format) |
+| `design` | Generate/update visual designs from codebase (Pencil.dev sync) |
+
+### CLI Commands
+
+| Command | Description |
+|---|---|
+| `godd-a install [--license-key=KEY]` | Register MCP server with Cursor |
+| `godd-a init [--force] [--lang=LANG] [--auto]` | Generate project config.godd |
+| `godd-a uninstall` | Remove MCP server from Cursor |
+| `godd-a serve` | Start MCP stdio server (auto-invoked by Cursor) |
+
+### Getting a License Key
+
+A license key is required to use GoDD MCP. Follow these steps:
+
+1. Check plans at the [GoDD official site](https://www.getgodd.dev/pricing)
+2. [Register an account](https://www.getgodd.dev/godd-admin/register) and purchase a subscription
+3. Issue a license key from your [dashboard](https://www.getgodd.dev/godd-admin/dashboard)
+
+Set the issued license key with `godd-a install --license-key=YOUR_KEY`.
+
+### Requirements
+
+- Node.js 22+
+- Cursor IDE
+- GoDD license key (get one at [official site](https://www.getgodd.dev/pricing))
+
+### Troubleshooting
+
+#### "0 tools available" is shown
+
+If Cursor's MCP log shows errors like:
+
+```
+Unexpected end of JSON input
+Unexpected token 'G', "GoDD MCP α"... is not valid JSON
+```
+
+**Cause**: `mcp.json` `args` does not include `"serve"`. Without it, the installer mode starts (human-readable text output) and breaks the JSON-RPC communication Cursor expects.
+
+**Fix**:
+
+```bash
+# Reinstall to regenerate mcp.json correctly
+npx -y @autodevjapan/godd-mcp-alpha install --license-key=YOUR_KEY
+```
+
+Then restart Cursor.
+
+#### License key is bound to another device
+
+GoDD license keys are bound to a device. To use on a different device, issue a new license key.
+
+```bash
+godd-a install --license-key=NEW_LICENSE_KEY
+```
+
+### License
+
+Proprietary — A GoDD license key is required. Purchase at the [official site](https://www.getgodd.dev/pricing).
+
+---
+
+## 日本語
+
 Cursor IDE 向けの AI プロンプト配信システム。MCP (Model Context Protocol) を通じて、プロジェクトの技術スタックに最適化されたプロンプト・マインドセット・エージェント定義を提供します。
 
-## インストール
+### インストール
 
 ```bash
 npm install -g @autodevjapan/godd-mcp-alpha
 ```
 
-## セットアップ（推奨）
+### セットアップ（推奨）
 
 ```bash
 # Cursor IDE に MCP サーバーを登録（mcp.json を自動生成）
@@ -21,12 +169,12 @@ godd-a init
 godd-a init --auto
 ```
 
-> **`godd-a install` を使ってください。** mcp.json の手動編集は非推奨です。  
+> **`godd-a install` を使ってください。** mcp.json の手動編集は非推奨です。
 > `godd-a install` は起動コマンド・PATH・ライセンスキーを正しく設定します。
 
-## mcp.json を手動で設定する場合
+### mcp.json を手動で設定する場合
 
-`godd-a install` が使えない環境では、`~/.cursor/mcp.json` を直接編集できます。  
+`godd-a install` が使えない環境では、`~/.cursor/mcp.json` を直接編集できます。
 **`serve` 引数は必須です。** 省略するとインストーラーモードで起動し、MCP 通信が破綻します。
 
 ```json
@@ -43,13 +191,13 @@ godd-a init --auto
 }
 ```
 
-## 使い方
+### 使い方
 
 インストール後、Cursor IDE を再起動すると GoDD MCP α サーバーが自動で起動します。
 
-Cursor のチャットで `dev`、`review` 等のツールを AI に呼び出させるか、`@godd-a` でプロンプトを指定して使用します。
+Cursor のチャットで AI に使いたいツールを指示してください（例：「dev して」「レビューして」）。AI が GoDD のツールを自動的に検出して呼び出します。
 
-## GoDD プロンプト一覧
+### GoDD プロンプト一覧
 
 Cursor IDE 上で利用できる GoDD プロンプト（MCP ツール）の一覧です。
 
@@ -73,14 +221,13 @@ Cursor IDE 上で利用できる GoDD プロンプト（MCP ツール）の一
 | `config` | config.godd を正確に生成・修正する（スタック自動検出 + バリデーション） |
 | `questions` | 質問リスト（質問リスト.md）からインタラクティブに質問を管理 |
 | `e2e` | ブラウザベース E2E テスト（重要ユーザーフローの実行・検証） |
-| `benchmark` | 競合プロンプト分析（GoDD vs Cursor Rules / Claude Code / Codex を比較） |
 | `map` | プロジェクトナレッジグラフ（Mermaid でアーキテクチャ・依存関係を可視化） |
 | `learn` | プロジェクト固有のパターン・慣例・落とし穴を保存/参照 |
 | `diagram` | アーキテクチャ図の自動更新（コードと同期した Mermaid ドキュメントを維持） |
 | `slide` | プロジェクトドキュメントからプレゼンスライドを生成（Marp Markdown 形式） |
 | `design` | コードベースからビジュアルデザインを生成/更新（Pencil.dev 同期） |
 
-## CLI コマンド
+### CLI コマンド
 
 | コマンド | 説明 |
 |---|---|
@@ -89,7 +236,7 @@ Cursor IDE 上で利用できる GoDD プロンプト（MCP ツール）の一
 | `godd-a uninstall` | Cursor から MCP サーバーを削除 |
 | `godd-a serve` | MCP stdio サーバーを起動（Cursor が自動呼び出し） |
 
-## ライセンスキーの取得
+### ライセンスキーの取得
 
 GoDD MCP を利用するにはライセンスキーが必要です。以下の手順で取得できます。
 
@@ -99,15 +246,15 @@ GoDD MCP を利用するにはライセンスキーが必要です。以下の
 
 発行されたライセンスキーを `godd-a install --license-key=YOUR_KEY` で設定してください。
 
-## 動作要件
+### 動作要件
 
 - Node.js 22 以上
 - Cursor IDE
 - GoDD ライセンスキー（[公式サイト](https://www.getgodd.dev/pricing)で取得）
 
-## トラブルシューティング
+### トラブルシューティング
 
-### 「利用可能なツールが 0 個」と表示される
+#### 「利用可能なツールが 0 個」と表示される
 
 Cursor の MCP ログに以下のようなエラーが出ている場合:
 
@@ -127,7 +274,7 @@ npx -y @autodevjapan/godd-mcp-alpha install --license-key=YOUR_KEY
 
 その後 Cursor を再起動してください。
 
-### ライセンスキーが別の端末に紐づいていると表示される
+#### ライセンスキーが別の端末に紐づいていると表示される
 
 GoDD のライセンスキーは端末（デバイス）に紐づきます。別端末で使用する場合は新しいライセンスキーを発行してください。
 
@@ -135,6 +282,148 @@ GoDD のライセンスキーは端末（デバイス）に紐づきます。別
 godd-a install --license-key=NEW_LICENSE_KEY
 ```
 
-## ライセンス
+### ライセンス
 
 Proprietary — GoDD ライセンスキーが必要です。[公式サイト](https://www.getgodd.dev/pricing)からご購入いただけます。
+
+---
+
+## Русский
+
+Система доставки AI-промптов для Cursor IDE. Предоставляет оптимизированные под технологический стек проекта промпты, мировоззрения и определения агентов через MCP (Model Context Protocol).
+
+### Установка
+
+```bash
+npm install -g @autodevjapan/godd-mcp-alpha
+```
+
+### Настройка (рекомендуется)
+
+```bash
+# Зарегистрировать MCP-сервер в Cursor IDE (автоматическая генерация mcp.json)
+godd-a install --license-key=YOUR_LICENSE_KEY
+
+# Автоматическая генерация config.godd для проекта (интерактивный режим)
+godd-a init
+
+# Или полностью автоматический режим (для CI/CD)
+godd-a init --auto
+```
+
+> **Используйте `godd-a install`.** Ручное редактирование mcp.json не рекомендуется.
+> `godd-a install` корректно настраивает команду запуска, PATH и лицензионный ключ.
+
+### Ручная настройка mcp.json
+
+Если `godd-a install` недоступен, можно напрямую отредактировать `~/.cursor/mcp.json`.
+**Аргумент `serve` обязателен.** Без него запускается режим установщика, и MCP-коммуникация нарушается.
+
+```json
+{
+  "mcpServers": {
+    "godd-a": {
+      "command": "npx",
+      "args": ["-y", "@autodevjapan/godd-mcp-alpha@latest", "serve"],
+      "env": {
+        "GODD_LICENSE_KEY": "GODD-XXXX-XXXX"
+      }
+    }
+  }
+}
+```
+
+### Использование
+
+После установки перезапустите Cursor IDE — сервер GoDD MCP α запустится автоматически.
+
+В чате Cursor просто попросите AI использовать нужный инструмент (например, «запусти dev», «сделай review»). AI автоматически обнаружит и вызовет соответствующий инструмент GoDD.
+
+### Список промптов GoDD
+
+Доступные промпты GoDD (MCP-инструменты) в Cursor IDE:
+
+| Промпт | Описание |
+|---|---|
+| `dev` | Разработка (поэтапно: план → реализация → тесты → качество → документация) |
+| `check` | Контроль качества (проверка соответствия спецификации, тесты, типы, линтер, безопасность) |
+| `docs` | Генерация/обновление документации |
+| `ship` | Отправка (коммит с правильной гранулярностью → проверка качества → push → создание PR) |
+| `setup` | Настройка среды (с рекомендуемыми пресетами стека, уточнение недостающей информации) |
+| `review` | Ревью (уровень CTO + контроль качества) |
+| `test` | Запуск/создание тестов |
+| `impact` | Анализ влияния |
+| `commit` | Коммит изменений |
+| `push` | Push на удалённый репозиторий |
+| `pr` | Создание PR (по шаблону) |
+| `deploy` | Деплой (с верификацией и планом отката) |
+| `adr` | Создание ADR (Architecture Decision Record) |
+| `release` | Генерация заметок к релизу (SemVer-совместимые) |
+| `github` | Настройка GitHub (защита репозитория/веток и т.д.) |
+| `config` | Генерация/исправление config.godd (автодетект стека + валидация) |
+| `questions` | Управление списком вопросов (質問リスト.md) в интерактивном режиме |
+| `e2e` | E2E-тестирование в браузере (выполнение и проверка критических пользовательских потоков) |
+| `map` | Граф знаний проекта (визуализация архитектуры и зависимостей через Mermaid) |
+| `learn` | Сохранение/вызов специфичных для проекта паттернов, соглашений и подводных камней |
+| `diagram` | Автообновление архитектурных диаграмм (поддержка актуальных Mermaid-документов) |
+| `slide` | Генерация презентационных слайдов из документации проекта (формат Marp Markdown) |
+| `design` | Генерация/обновление визуального дизайна из кодовой базы (синхронизация с Pencil.dev) |
+
+### Команды CLI
+
+| Команда | Описание |
+|---|---|
+| `godd-a install [--license-key=KEY]` | Зарегистрировать MCP-сервер в Cursor |
+| `godd-a init [--force] [--lang=LANG] [--auto]` | Сгенерировать config.godd для проекта |
+| `godd-a uninstall` | Удалить MCP-сервер из Cursor |
+| `godd-a serve` | Запустить MCP stdio-сервер (автоматически вызывается Cursor) |
+
+### Получение лицензионного ключа
+
+Для использования GoDD MCP необходим лицензионный ключ. Получите его следующим образом:
+
+1. Ознакомьтесь с тарифными планами на [официальном сайте GoDD](https://www.getgodd.dev/pricing)
+2. [Зарегистрируйте аккаунт](https://www.getgodd.dev/godd-admin/register) и приобретите подписку
+3. Выпустите лицензионный ключ в [личном кабинете](https://www.getgodd.dev/godd-admin/dashboard)
+
+Установите полученный ключ командой `godd-a install --license-key=YOUR_KEY`.
+
+### Системные требования
+
+- Node.js 22+
+- Cursor IDE
+- Лицензионный ключ GoDD (получите на [официальном сайте](https://www.getgodd.dev/pricing))
+
+### Устранение неполадок
+
+#### Отображается «0 доступных инструментов»
+
+Если в логах MCP Cursor отображаются ошибки вида:
+
+```
+Unexpected end of JSON input
+Unexpected token 'G', "GoDD MCP α"... is not valid JSON
+```
+
+**Причина**: В `args` файла `mcp.json` отсутствует `"serve"`. Без него запускается режим установщика (текстовый вывод для человека), что нарушает JSON-RPC коммуникацию, ожидаемую Cursor.
+
+**Решение**:
+
+```bash
+# Переустановите для правильной регенерации mcp.json
+npx -y @autodevjapan/godd-mcp-alpha install --license-key=YOUR_KEY
+```
+
+Затем перезапустите Cursor.
+
+#### Лицензионный ключ привязан к другому устройству
+
+Лицензионные ключи GoDD привязываются к устройству. Для использования на другом устройстве выпустите новый ключ.
+
+```bash
+godd-a install --license-key=NEW_LICENSE_KEY
+```
+
+### Лицензия
+
+Проприетарная — требуется лицензионный ключ GoDD. Приобретите на [официальном сайте](https://www.getgodd.dev/pricing).