Dev Workflow MCP Server

🚀 開発ワークフローMCPサーバー

開発の規律とワークフローのベストプラクティスを強制するのに役立つMCP（モデルコンテキストプロトコル）サーバーです。このサーバーは、適切な開発ワークフローに従うようにあなたにアドバイスするコーディングの良心のような存在です。

🚀 クイックスタート

このMCPサーバーを使用することで、規律正しい開発ワークフローを進めることができます。まずは、以下の手順でサーバーをインストールし、設定を行いましょう。

✨ 主な機能

🛡️ レジリエンス機能

• 起動時のレジリエンス：外部データベースへの接続タイムアウトを5秒に設定します。
• バックグラウンドローディング：重要ではないアセット（互換性ミラー）はバックグラウンドで初期化され、サブ秒単位での起動を保証します。
• 診断モード：自動的に起動タイミングのログがstderrに表示されます。

📦 インストール

オプション1：プロジェクトの依存関係としてインストール（推奨）

各プロジェクトに独立したワークフロー状態ファイルが作成されます。

npm install @programinglive/dev-workflow-mcp-server

これにより、npm installを実行したプロジェクト内に.state/workflow-state.jsonファイルが自動的に作成され、各プロジェクトのワークフロー履歴が分離されます。パッケージ自体をインストールする場合（node_modules内）、スクリプトは作成をスキップし、共有パッケージディレクトリを汚染することはありません。

オプション2：ソースからインストール

git clone https://github.com/programinglive/dev-workflow-mcp-server.git
cd dev-workflow-mcp-server
npm install

Windowsの前提条件：ソースから依存関係をインストールすると、better-sqlite3などのネイティブモジュールがコンパイルされます。npm installを実行する前に、Python 3（PATHに追加）とVisual Studio Build Toolsの「C++でのデスクトップ開発」ワークロードをインストールしてください。これらがないと、npmは「pythonが必要」またはビルドエラーで失敗します。

オプション3：Pleskホスティングでのインストール

PleskはNode.js拡張機能を通じてNode.jsアプリケーションをサポートしています。PleskサブスクリプションにMCPサーバーをデプロイするには、以下の手順を実行します。

1. Node.jsサポートを有効にする：Plesk管理者がNode.js拡張機能をインストールし、サブスクリプションにSSHアクセスを有効にしていることを確認します。
2. プロジェクトをアップロードする：リポジトリをクローンするか、アーカイブを実行するディレクトリ（例：httpdocs/dev-workflow-mcp-server）にアップロードします。SSHから以下のコマンドを実行できます。

   cd httpdocs
   git clone https://github.com/programinglive/dev-workflow-mcp-server.git
   cd dev-workflow-mcp-server
   

3. 依存関係をインストールする：Pleskの「Node.js」パネルで「NPM install」を使用するか（またはSSHでnpm install --productionを実行します）。Linuxホストにはbetter-sqlite3に必要なPython/ビルドツールチェーンがすでにインストールされています。Windowsホストを使用する場合は、事前にPython 3とVisual Studio Build Toolsをインストールするか、プロバイダーに有効にしてもらいます。
4. 環境変数を定義する：Node.jsパネルで必要な環境変数を追加します（例：DEV_WORKFLOW_USER_IDまたはDEV_WORKFLOW_STATE_FILE）。これにより、必要に応じて状態ファイルをウェブルート外に配置できます。
5. アプリケーションを構成する：「アプリケーション起動ファイル」をindex.jsに設定し、「アプリケーションモード」をproductionに設定します。Pleskはnode index.jsでサーバーを実行します。
6. アプリを起動/再起動する：「アプリを再起動」をクリックして、新しい設定でMCPサーバーを起動します。コードを更新した場合は、「NPM install」を再実行して再起動します。

ヒント：MCPサーバーはstdioを介して通信します。CLIツールとしてのみ必要な場合は、Node.jsパネルで実行することなく、SSHセッションで直接npx @programinglive/dev-workflow-mcp-serverを実行することもできます。

重要：MCPクライアント（Windsurf、Claude Desktopなど）は、stdioを介してサーバープロセスをローカルで起動する必要があります。ダッシュボードをパブリックドメインにホストしても、MCPインターフェースは公開されません。サーバーでnode index.jsを実行するためのSSHまたは他の方法がない限り、ユーザーはMCPクライアントをホストされたインスタンスに接続できません。

オプション4：Google CloudでのDockerを使用したデプロイ

DockerとPostgreSQLを使用して、MCPサーバーをGoogle Cloud Compute Engineにデプロイし、本番環境向けのクラウドホスト型セットアップを実現します。 クイックスタート：

1. GCPインスタンスにSSHで接続します。
2. セットアップスクリプトを実行します：bash scripts/setup-gcp-instance.sh
3. リポジトリをクローンし、.envを構成します。
4. コンテナを起動します：docker-compose up -d
5. ローカルのMCPクライアント設定を更新して、SSH経由で接続します。

利点：

• ✅ 堅牢なデータ永続性のためのPostgreSQLデータベース
• ✅ 一貫性のあるコンテナ化されたデプロイ
• ✅ SSHトンネリングによるリモートアクセス
• ✅ 簡単な更新とロールバック

詳細な手順については、GCPデプロイメントガイドを参照してください。

💻 使用例

基本的な使用法

1. サーバーを起動する

サーバーを起動するには、以下のコマンドを実行します。

node index.js

2. クライアントを設定する

異なるクライアントでMCPサーバーを使用するには、以下の手順で設定を行います。

2.1 Windsurf/Claude Desktopでの設定

MCPクライアントをサーバーのエントリポイントに設定します。<PROJECT_ROOT>をマシン上のこのリポジトリの絶対パスに置き換えます。

macOS

• Windsurf (~/Library/Application Support/Windsurf/config.json)：

{
  "mcpServers": {
    "dev-workflow": {
      "command": "node",
      "cwd": "<PROJECT_ROOT>",
      "args": ["index.js"],
      "env": {
        "DEV_WORKFLOW_DB_TYPE": "postgres",
        "DEV_WORKFLOW_DB_URL": "postgres://USER:PASS@HOST:5432/devworkflow"
      }
    }
  }
}

• Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json)：

{
  "mcpServers": {
    "dev-workflow": {
      "command": "node",
      "args": ["<PROJECT_ROOT>/index.js"]
    }
  }
}

Windows

• Windsurf (%APPDATA%\Windsurf\config.json)：

{
  "mcpServers": {
    "dev-workflow": {
      "command": "node",
      "args": ["<PROJECT_ROOT>\\index.js"]
    }
  }
}

• Claude Desktop (%APPDATA%\Claude\claude_desktop_config.json)：

{
  "mcpServers": {
    "dev-workflow": {
      "command": "node",
      "args": ["<PROJECT_ROOT>\\index.js"]
    }
  }
}

Linux

• Windsurf (~/.config/windsurf/config.json)：

{
  "mcpServers": {
    "dev-workflow": {
      "command": "node",
      "args": ["<PROJECT_ROOT>/index.js"]
    }
  }
}

• Claude Desktop (~/.config/claude/claude_desktop_config.json)：

{
  "mcpServers": {
    "dev-workflow": {
      "command": "node",
      "args": ["<PROJECT_ROOT>/index.js"]
    }
  }
}

注意：Windowsでは、JSON内のパスにはエスケープされたバックスラッシュが必要です（例："C:\\path\\to\\project"）。

macOSでのWindsurf MCP設定の完全な例

このリポジトリを/Users/alex/code/dev-workflow-mcp-serverにチェックアウトし、WindsurfをホストされたPostgreSQLインスタンスに向ける場合は、以下の内容を~/Library/Application Support/Windsurf/mcp_config.jsonに追加します。

{
  "mcpServers": {
    "dev-workflow": {
      "command": "node",
      "cwd": "/Users/alex/code/dev-workflow-mcp-server",
      "args": ["index.js"],
      "env": {
        "DEV_WORKFLOW_DB_TYPE": "postgres",
        "DEV_WORKFLOW_DB_URL": "postgres://devworkflow:devworkflow_secure_password@34.50.121.142:5432/devworkflow"
      }
    }
  }
}

これは、以前のリリースで共有されたWindowsの設定を反映していますが、macOSでのnpxルックアップの問題を回避するために、ローカルのindex.jsを直接起動します。

3. Windsurf/Claude Desktopを再起動する

設定を追加した後、アプリケーションを再起動してMCPサーバーを読み込みます。

4. Antigravityでの設定

Antigravityユーザーは、mcp_config.jsonでMCPサーバーを設定する必要があります。 Windows：%APPDATA%\Antigravity\mcp_config.jsonまたはC:\Users\<USERNAME>\.gemini\antigravity\mcp_config.json

{
  "mcpServers": {
    "dev-workflow": {
      "command": "node",
      "args": ["<PROJECT_ROOT>\\index.js"]
    }
  }
}

詳細な手順とトラブルシューティングについては、Antigravity Getting Startedを参照してください。

高度な使用法

⚡ パフォーマンス最適化（推奨）

Claude DesktopのようなIDE統合クライアントで可能な限り速い起動を確保するために、npxではなくnodeを使用して直接index.jsを指定することをお勧めします。これにより、パッケージの更新チェックのオーバーヘッドを回避できます。 最適化された設定：

{
  "mcpServers": {
    "dev-workflow": {
      "command": "node",
      "args": ["<PROJECT_ROOT>\\index.js"],
      "env": {
        "DEV_WORKFLOW_USER_ID": "your_user_id"
      }
    }
  }
}

サーバーは自動的に起動時間を計測し、stderrにログを出力します。 Dev Workflow MCP Server running on stdio (startup took 15ms)

📚 ドキュメント

データベースの設定

サーバーは、SQLite（デフォルト）、MySQL、およびPostgreSQLをサポートしています。

.envを使用した設定

1. .env.exampleを.envにコピーします。

   cp .env.example .env
   

2. .envを編集して設定を行います。

   DEV_WORKFLOW_DB_TYPE=mysql
   DEV_WORKFLOW_DB_URL=mysql://user:pass@localhost:3306/db
   

環境変数を使用した設定

あるいは、直接変数をエクスポートすることもできます。

変数	説明	デフォルト
DEV_WORKFLOW_DB_TYPE	データベースドライバー (sqlite, mysql, postgres)	sqlite
DEV_WORKFLOW_DB_URL	MySQL/Postgresの接続文字列	null
DEV_WORKFLOW_DB_PATH	SQLiteデータベースファイルのパスを上書き	<project>/.state/dev-workflow.db

例

MySQL：

export DEV_WORKFLOW_DB_TYPE=mysql
export DEV_WORKFLOW_DB_URL="mysql://user:password@localhost:3306/dev_workflow"

PostgreSQL：

export DEV_WORKFLOW_DB_TYPE=postgres
export DEV_WORKFLOW_DB_URL="postgresql://user:password@localhost:5432/dev_workflow"

🛠️ データベーススキーマの正規化（Postgres/MySQL）

既存のレポートダッシュボードとの互換性を確保するために、PostgresAdapterとMysqlAdapterは自動的に列名を正規化します。

• task_description → データベース列：description
• timestamp → データベース列：completed_at アダプターはクエリでエイリアスを使用するため、MCPツールは依然として期待されるtask_descriptionとtimestampフィールドを受け取ります。

👤 ユーザーIDの処理（Postgres/MySQL）

これらのデータベースは、user_idにINTEGER列を使用します。

• 数値文字列（例："1"）は直接整数に解析されます。
• 非数値文字列（例："programinglive"）は自動的に一貫した正の整数にハッシュされ、スキーマとの互換性を確保しながら、ユニークなユーザー分離を維持します。

ユーザーと状態の管理

変数	説明
DEV_WORKFLOW_USER_ID	自動生成されたユーザーIDを上書き（例：あなたの名前/メールアドレスを設定）
DEV_WORKFLOW_STATE_FILE	workflow-state.jsonファイルの場所を上書き

複数のクライアントを使用する場合（Antigravity & Windsurf）

同じプロジェクトで複数のAIコーディングツール（例：AntigravityとWindsurf）を同時に使用する場合、デフォルトでは同じワークフロー状態を共有します。 各ツールに個別のセッションを維持するには、それぞれに一意のDEV_WORKFLOW_USER_IDを設定します。 Antigravityの設定 (mcp_config.json)：

{
  "mcpServers": {
    "dev-workflow": {
      "command": "node",
      "args": ["path/to/server/index.js"],
      "env": {
        "DEV_WORKFLOW_USER_ID": "antigravity_user"
      }
    }
  }
}

Windsurfの設定： WindsurfのMCP設定に環境変数を追加します。

{
  "mcpServers": {
    "dev-workflow": {
      "command": "node",
      "args": ["path/to/server/index.js"],
      "env": {
        "DEV_WORKFLOW_USER_ID": "windsurf_user"
      }
    }
  }
}

✅ テスト

プロジェクトはNode.jsのネイティブテストランナー（node --test）を使用しています。

npm test

これにより、以下のテストが実行されます。

• ワークフローロジックの単体テスト
• .env設定の統合テスト
• DBアダプターのテスト（SQLiteは常に実行され、MySQL/Postgresは設定されている場合に実行されます）

データベースアダプターのテスト

MySQLまたはPostgreSQLアダプターを検証するには、環境変数を設定してテストを実行します。

# MySQLのテスト
export DEV_WORKFLOW_DB_URL="mysql://root:pass@localhost:3306/test_db"
node --test tests/db-adapters.test.js

# PostgreSQLのテスト
export DEV_WORKFLOW_DB_URL="postgres://postgres:pass@localhost:5432/test_db"
node --test tests/db-adapters.test.js

スクリプト

• npm run build - ソースをdist/index.mjsにバンドルして配布用にします。
• npm run dev - ファイル監視を使用して開発モードで実行します。
• npm run local - ソースから実行するためのエイリアス（npm startと同じ）
• npm run web - タスク履歴を閲覧するための軽量なワークフローダッシュボードを起動します（Web Dashboard docsを参照）

npm run web

このコマンドは、web/server.jsで定義されたダッシュボードを起動し、ワークフロー履歴と要約統計をすばやく表示します。

npm run web
# 🌐 Dev Workflow Dashboard running at http://localhost:3111

• デフォルトポート：3111（使用中の場合は次の空きポート）
• 環境の上書き：PORT（Plesk/Renderなどのホストで一般的）またはDEV_WORKFLOW_WEB_PORTを尊重し、自動選択にフォールバックします。
• クエリパラメータ：?user=<id>で別のユーザーの履歴を調べることができます（デフォルトはdefault）
• APIエンドポイント：
  • GET /api/version → package.jsonからの現在のパッケージバージョン（ダッシュボードが動的にバージョンを表示するために使用）
  • GET /api/summary?user=<id> → ユーザーの全体的な統計
  • GET /api/history?user=<id>&page=1&pageSize=20&startDate=YYYY-MM-DD&endDate=YYYY-MM-DD → ページネーションされたタスク履歴
  • GET /api/history-summary?user=<id>&frequency=daily|monthly|yearly → 時間の経過に伴う集計されたカウント ブラウザでhttp://localhost:3111を開いて、ダッシュボードUI（web/index.html）を表示します。

ビルド出力

npm run buildを実行すると、以下のものが生成されます。

• dist/index.mjs - 最適化されたESモジュールバンドル
• ソースマップとその他のビルドアーティファクト
• dist/docs/ - scripts/build-docs.jsを介してMarkdownから生成された事前レンダリングされたHTMLドキュメント ビルドはすべてのソースファイルをバンドルし、Node.jsの組み込みモジュールと依存関係を外部化するため、単一のファイル配布が可能になります。

使用方法

MCPサーバーを使用する場合は、stdioトランスポートの互換性の問題を回避するために、クライアントをindex.js（ソース）に設定します。ビルドされたdist/index.mjsは主に以下の用途に使用されます。

• npmパッケージの配布
• パフォーマンスの最適化
• 他のプロジェクトへの埋め込み

MCPツールレジストリ（公開）

このパッケージは、npmパッケージデプロイメントを使用して公式のMCPツールレジストリに設定されています。

• package.jsonはmcpName: "io.github.programinglive/dev-workflow-mcp-server"を宣言しています。
• server.jsonはサーバーを説明し、npmパッケージ@programinglive/dev-workflow-mcp-serverにリンクしています。 新しいサーバーバージョンをレジストリに公開するには、以下の手順を実行します。

1. 新しいnpmバージョンをリリースします（例）：
   • npm test
   • npm run release:patch（既存のリリースパイプラインを実行し、npmに公開します）
2. 新しいバージョンがnpmに存在することを確認します：
   • npm view @programinglive/dev-workflow-mcp-server version
3. MCPパブリッシャーCLIをインストールします（マシンごとに1回）：
   • brew install mcp-publisher（またはhttps://modelcontextprotocol.info/tools/registry/publishing/のドキュメントに従ってください）
4. このリポジトリのルートから、認証して公開します：
   • mcp-publisher login github
   • mcp-publisher publish
5. 必要に応じて、レジストリで確認します：
   • curl "https://registry.modelcontextprotocol.io/v0/servers?search=io.github.programinglive/dev-workflow-mcp-server"

PowerShell CLIのヒント

PowerShellから軽量なCLIを呼び出す場合は、--%を使用してPowerShellがJSON引数を書き換えるのを防ぎます。例：

node --% index.js call start_task --args "{\"description\":\"Convert docs to HTML during build\",\"type\":\"feature\"}"

--%接頭辞とエスケープされた二重引用符により、JSONがMCPサーバーに変更されずに到達します。

📁 プロジェクト固有のワークフロー状態

このパッケージをプロジェクトにインストールすると、プロジェクトルートに.state/workflow-state.jsonファイルが自動的に作成されます。このファイルは以下の情報を格納します。

• そのプロジェクト固有のワークフロー履歴
• 各タスクの進行状況
• gitで無視する必要があります（デフォルトで.gitignoreに含まれています）
• セッション間で持続します：ワークフロー状態が保存されます
• 集中管理されます：dist/などのネストされたビルド出力からサーバーを実行しても、MCPサーバーは.gitまたはpackage.jsonを探してプロジェクトルートに戻り、ワークフロー状態を読み書きするため、ビルドディレクトリの下に重複したコピーを作成する必要はありません。 各プロジェクトは独自の独立したワークフロー履歴を維持するため、複数のプロジェクトで作業しても履歴が混ざることはありません。.stateディレクトリ内で、MCPサーバーは自動的にユーザーごとの一意のサブディレクトリ（例：.state/users/user-abc123/）を作成します。生成された識別子はローカルに保持されるため、同じリポジトリを共有する複数の開発者がワークフローファイルを上書きすることはありません。特定の名前を使用する場合は、サーバーを起動する前にDEV_WORKFLOW_USER_IDを設定すると、自動生成されたIDの代わりにその値が使用されます。

ユーザーIDの選択

使用例：

1. サーバーに選択させる：何もしないと、最初にMCPツールを実行したときにサーバーが.state/users/<random-id>/を作成します。ダッシュボードの「ユーザーID」フィルターはその値を受け付けます（フォルダ名またはワークフロー応答に表示されます）。
2. 明示的なIDを設定する：サーバーを起動する前に、DEV_WORKFLOW_USER_IDをエクスポートします。

   # macOS/Linux
   export DEV_WORKFLOW_USER_ID=alice
   node index.js
   
   # Windows PowerShell
   $env:DEV_WORKFLOW_USER_ID = "alice"
   node index.js
   

   これで、そのセッションのすべての履歴が.state/users/alice/に保存され、ダッシュボードをaliceでフィルタリングできます。
3. 1つのホストで複数のユーザーを使用する：異なるDEV_WORKFLOW_USER_ID値で別々のプロセス（またはMCPクライアント）を実行します。各ユーザーのワークフロー状態は分離されたままです。

ヒント：ウェブダッシュボードは単に既存のレコードを読み取ります。「ユーザーID」フィルターに新しい値を入力すると、ワークフローセッションが.state/users/<that-id>/に履歴を書き込んだ後にのみ結果が返されます。

.gitignoreへの追加

このパッケージを使用している場合は、プロジェクトの.gitignoreに以下を追加します。

.state/

これにより、ワークフロー状態が各開発者のマシンにローカルに保持されます。

場所を上書きする必要がありますか？ サーバーを起動する前に（またはMCPクライアントの設定内で）DEV_WORKFLOW_STATE_FILE=/absolute/path/to/your/project/.state/workflow-state.jsonを設定します。サーバーはそのパスを尊重し、パッケージを集中的にインストールしながらも、プロジェクトごとのワークフロー履歴を維持できます。

🛠️ 利用可能なツール

• start_task - 新しいコーディングタスクを開始します。
• mark_bug_fixed - 機能/バグが修正されたことをマークします（次にテストが必要です）。
• create_tests - テストが作成されたことをマークします。
• skip_tests - 正当な理由でテストをスキップします。
• run_tests - テスト結果を記録します（続行するにはすべてのテストが合格する必要があります）。
• create_documentation - ドキュメントが作成されたことをマークします。
• check_ready_to_commit - すべての手順が完了していることを確認します。
• commit_and_push - 変更をコミットしてプッシュします。
• perform_release - リリースの詳細を記録します（または、プロジェクトにリリース自動化がない場合はskip_releaseを使用します）。
• complete_task - タスクを完了とマークし、リセットします。
• force_complete_task - 理由を付けてタスクを強制的に完了します。
• drop_task - 現在のタスクを放棄します。
• get_workflow_status - 現在のステータスを表示します。
• view_history - 完了したタスクの履歴を表示します。
• continue_workflow - 次の手順のガイダンスを取得します。
• rerun_workflow - 現在のタスクを最初からリセットして再開します。
• run_full_workflow - すべてのワークフロー手順を1つのコマンドで順番に実行します（各フェーズの詳細を提供する必要があります）。

run_full_workflow

各ワークフローフェーズに必要なすべての情報がすでにあり、一度に実行したい場合は、このコマンドを使用します。

{
  "summary": "Add payment webhooks",
  "testCommand": "npm test",
  "documentationType": "README",
  "documentationSummary": "Document webhook configuration",
  "commitMessage": "feat: add payment webhooks",
  "releaseCommand": "npm run release:minor",
  "releaseNotes": "Release webhook support",
  "branch": "feature/payments",
  "testsPassed": true,
  "testDetails": "node --test; 42 tests",
  "releaseType": "minor",
  "preset": "minor"
}

ツールは以下の手順を実行します。

1. mark_bug_fixedをsummaryを使用して実行します。
2. create_testsを実行します。
3. run_testsをtestsPassed、testCommand、およびオプションのtestDetailsを使用して実行します。
4. create_documentationをdocumentationTypeとdocumentationSummaryを使用して実行します。
   • 必要条件：ドキュメントを完了とマークする前に、docs/product/PRD.mdにPRD（製品要件文書）が存在する必要があります。
5. check_ready_to_commitを実行します。
6. commit_and_pushをcommitMessageとオプションのbranchを使用して実行します。
7. perform_releaseをreleaseCommand、およびオプションのreleaseNotes、releaseType、およびpresetを使用して実行します。
   • あるいは、リポジトリにNodeベースのリリースステップがない場合（例：Pythonのみまたはドキュメントのみのタスク）は、skip_releaseを正当な理由とともに呼び出します。
8. complete_taskをcommitMessageを再利用して実行します。 すべての引数は、オプションのフラグを除いて必須であり、空でない文字列である必要があります。

ドキュメントの要件

create_documentationステップでは、ドキュメントを完了とマークする前に、docs/product/PRD.mdにPRD（製品要件文書）が存在することが必須です。これにより、すべてのプロジェクトが製品の目標、機能、および要件を記述する最新のPRDを維持することが保証されます。

🚫 ワークフローステップなしでのリリース

パッケージには、npm run release:*スクリプトをサポートするリリースガード（release-wrapper.js）が付属しています。ガードは、以下の条件を満たさない限り実行を拒否します。

• 現在のワークフローフェーズがリリースであること。
• check_ready_to_commitとcommit_and_pushが完了していること。
• アクティブなタスクに対してすでにリリースが記録されていないこと。 要件が欠けている場合、ガードはMCPツールに戻るようにガイダンスを表示して終了します。これにより、管理されたワークフロー外で誤ってバージョンを上げたり、リリースをタグ付けしたりすることが防止されます。正しくリリースするには、以下の手順を実行します。

1. MCPクライアントを介してperform_release {"command":"patch"}（またはminor/major）を使用するか、リリースが適用されない場合はskip_release {"reason":"<説明>"}を使用します。
2. ガードが自動的に実行され、ワークフロー状態を検証し、リリースを記録してから、complete_taskで終了できます。

npmの自動公開

このリポジトリには.github/workflows/npm-publish.ymlが含まれており、v*に一致するgitタグがプッシュされるたびに（例：v1.1.14）、パッケージがnpmに公開されます。ワークフローを有効にするには、以下の手順を実行します。

1. 公開権限を持つnpm自動化トークンを作成します（npm token create --read-only false）。
2. リポジトリの設定で、NPM_TOKEN という名前のシークレットにそのトークンを追加します。
3. リリースプロセスがnpm run release:<type>を実行した後にタグをプッシュするようにして、ワークフローがトリガーされるようにします。
4. ローカルでnpm run buildが成功することを確認します。ワークフローは公開前にビルドを実行するため、壊れたバンドルはリリースをブロックします。
5. GitHubのプロベナンスはnpm publish --provenanceを介して有効になっています。GitHub ActionsのデフォルトのOIDCパーミッションを有効にしておくと、ジョブがIDトークンを要求できます。
6. package.jsonのrepository.urlフィールドをこのGitHubリポジトリに設定しておきます。プロベナンスの検証は、パッケージをビルドしたリポジトリと一致しない場合に失敗します。 ワークフローは、公開前にタグのバージョンがpackage.jsonと一致することを検証し、不一致の場合はすぐに失敗します。

ツールの引数要件

すべてのツールの呼び出しは、実行前にargumentsペイロードを検証します。

• 文字列はJSONとして解析され、オブジェクト（キー/値のペア）に解決する必要があります。
• 非オブジェクトデータ（数値、配列、平文）を渡すと、ガイダンスエラーがトリガーされます。
• 欠落または形式が誤った引数は安全に空の入力にデフォルトされるため、ツールは実行可能なリマインダーで応答できます。

例（文字列化されたJSONオブジェクト）：

{
  "name": "start_task",
  "arguments": "{\"description\":\"Add reporting endpoint\",\"type\":\"feature\"}"
}

start_task

新しいコーディングタスクを開始します。これは最初のステップで、コーディングする内容を明確にします。 パラメーター：

• description（文字列、必須）：コーディングする内容の明確な説明
• type（列挙型、必須）：タスクのタイプ - "feature", "bugfix", "refactor", または "other" 例：

以下のパラメーターでstart_taskツールを使用します。
- description: "Add user authentication to the login page"
- type: "feature"

mark_bug_fixed

バグ/機能が修正されたことをマークします。リマインダー：次にテストを作成する必要があります！ パラメーター：

• summary（文字列、必須）：修正/実装された内容の簡単な要約

create_tests

変更をカバーする必要なテストが作成されたことを確認します。テスト結果を記録する前に必須です。 パラメーター：なし

skip_tests

自動テストが実行できない場合の明示的な正当理由を記録します。テストを満たしたとマークして、ドキュメント作成と検証を続行できるようにしますが、タスクを手動QAの対象としてフラグ付けします。 パラメーター：

• reason（文字列、必須）：自動テストをスキップした理由

run_tests

テスト結果を記録します。テストが失敗した場合は決してコミットしないでください！ すべてのテストが合格した場合のみ続行してください。 パラメーター：

• passed（ブール値、必須）：すべてのテストが合格したかどうか
• testCommand（文字列、必須）：実行されたテストコマンド
• details（文字列、オプション）：テスト結果の詳細 例：

以下のパラメーターでrun_testsを使用します。
- passed: true
- testCommand: "npm test"
- details: "All 15 tests passed"

create_documentation

ドキュメントが作成/更新されたことをマークします。コミットする前に必須です。 パラメーター：

• documentationType（列挙型、必須）："PRD", "README", "RELEASE_NOTES", "inline-comments", "API-docs", "changelog", または "other"
• summary（文字列、必須）：ドキュメント化された内容

check_ready_to_commit

すべてのワークフローステップが完了していることを確認します。

commit_and_push

準備チェックが通過した後、自動的にgit add、git commit、およびgit pushを実行します。 メインブランチの自動検出：branchが指定されていない場合、ツールは最初にorigin/mainをチェックし、次にorigin/masterにフォールバックすることで、プロジェクトのメインブランチを自動的に検出します。これにより、ほとんどのプロジェクトでbranchパラメーターを指定する必要がなくなります。 パラメーター：

• commitMessage（文字列、必須）：使用するコンベンショナルコミットメッセージ
• branch（文字列、オプション）：プッシュするターゲットブランチ。省略した場合、メインブランチ（mainまたはmaster）が自動的に検出されます。

perform_release

コミットとプッシュの後、リリースを記録します。タスクを完了する前に必須です。 パラメーター：

• command（文字列、必須）：実行されたリリースコマンド（例：npm run release）
• notes（文字列、オプション）：追加のリリースノート

complete_task

コミットとプッシュが成功した後、タスクを完了とマークします。次のタスクのためにワークフローをリセットします。 パラメーター：

• commitMessage（文字列、必須）：使用されたコミットメッセージ

drop_task

ワークフローを完了せずに現在のタスクを放棄します。コンテキスト付きの監査エントリを保持し、状態をリセットして、新しく開始できるようにします。 パラメーター：

• reason（文字列、オプション）：タスクを放棄した理由の追加の詳細

get_workflow_status

現在のワークフローステータスと次に行うべきことを取得します。

view_history

完了したタスクのワークフロー履歴を表示します。 パラメーター：

• limit（数値、オプション）：表示する最近のタスクの数（デフォルト：10）

📋 利用可能なプロンプト

workflow_reminder

開発ワークフローの規律に関する完全なリマインダーを取得します。

pre_commit_checklist

コミットする前に何かを見落とさないようにするためのコミット前チェックリストを取得します。

🔄 典型的なワークフロー

以下は、典型的なコーディングセッションでこのMCPサーバーを使用する方法です。

1. タスクを開始する：

   Cascadeにstart_taskを使用するように依頼します。
   "Start a new task: implementing user profile page, type: feature"
   

2. 機能/修正をコーディングする
   • 通常通りコードを書きます。
3. 修正済みとマークする：

   "Mark the feature as fixed: User profile page with avatar and bio completed"
   

4. テストを作成する：
   • テストを書きます。
   • サーバーはこれが必須であることをリマインドします！
5. テストを実行する：

   "Record test results: passed=true, command='npm test'"
   

   • テストが失敗した場合、サーバーは進行をブロックします！
6. ドキュメントを作成する：

   "Create documentation: type=README, summary='Added user profile section to docs'"
   

7. 準備状況を確認する：

   "Check if I'm ready to commit"
   

8. コミットとプッシュする：

   "Commit and push: commitMessage='feat: add user profile page with tests and docs'"
   

9. リリースを記録する：

"Record release: command='npm run release', notes='v1.2.3'"

11. 完了する：

"Complete the task with commit message: 'feat: add user profile page'"

12. タスクを放棄する（オプション）：

"Drop task: reason='Switching to a different feature'"

🎯 主要な機能

• 規律を強制する：ステップをスキップすることはできません。
• テスト駆動：テストが失敗した場合はコミットをブロックします。
• ドキュメントリマインダー：作業をドキュメント化することを確認します。
• 状態追跡：ワークフローの現在の位置を記憶します。
• 履歴：完了したタスクを追跡します。
• プロンプト：ベストプラクティスの迅速なリマインダーを提供します。

🚫 このサーバーが防止すること

• ❌ テストなしでのコミット
• ❌ テストが失敗した状態でのコミット
• ❌ ドキュメントなしでのコミット
• ❌ 作業中の内容を見失うこと
• ❌ 重要なワークフローステップをスキップすること

💡 ヒント

1. 常にstart_taskから始める - 意図を設定します。
2. 正当な理由なしでテストをスキップしない - skip_testsは絶対に必要な場合のみ使用し、手動QAの理由をドキュメント化します。
3. get_workflow_statusを使用する - いつでも現在の位置を確認します。
4. 履歴を確認する - 過去のタスクから学びます。
5. プロンプトに従う - ベストプラクティスが含まれています。

🔧 カスタマイズ

index.jsでワークフローを変更することができます。

• より多くのワークフローフェーズを追加します。
• リマインダーをカスタマイズします。
• テストランナーとの統合を追加します。
• カスタム検証ルールを追加します。

📝 状態管理

サーバーは.state/workflow-state.jsonに状態を維持します。

• 現在のフェーズ
• タスクの説明
• 各ステップの完了状態
• 完了したタスクの履歴 このファイルはサーバーによって自動的に作成および管理されます。 これにはローカルのマシン固有の進捗状況が含まれており、gitによって無視されるため、各環境が独自のワークフロー履歴を管理し、相互汚染を防ぐことができます。

🤝 独自のルールとの統合

このMCPサーバーは、既存の開発ルールと一致します。

• ✅ テスト先行の規律を強制します。
• ✅ テストが失敗した状態でのコミットを防止します。
• ✅ ドキュメント化をリマインドします。
• ✅ ワークフロー状態を追跡します。
• ✅ 履歴を維持します。

📄 ライセンス

MIT

🙏 コントリビューション

このサーバーを独自のワークフローニーズに合わせて自由にカスタマイズしてください！

📜 プロジェクトのガバナンス

• 行動規範
• コントリビューションガイド
• セキュリティポリシー
• ライセンス