@geekbeer/minion 2.53.2 → 2.53.3

package/docs/environment-setup.md

@@ -0,0 +1,196 @@
+# 環境セットアップガイド
+
+スキルが必要とする MCP サーバーや CLI ツールのインストール・設定手順です。
+
+---
+
+## 事前チェック（Readiness Check）の仕組み
+
+スキルの `requires` フロントマターで宣言された依存関係は、ワークフロー実行前に事前チェックされる。
+
+```yaml
+requires:
+  mcp_servers: [playwright]
+  cli_tools: [jq, imagemagick]
+```
+
+| 種別 | 検出方法 | チェック対象 |
+|------|---------|-------------|
+| `mcp_servers` | `~/.mcp.json` を読み取り、`mcpServers` キーにサーバー名が存在するか確認 | 設定ファイルの有無のみ（実際の起動テストはしない） |
+| `cli_tools` | `which <tool>` でパスが通っているか確認 | コマンドの存在（バージョンも取得を試みる） |
+
+**重要**: MCP サーバーは `~/.mcp.json` に設定しないと検出されない。npm パッケージをインストールしただけでは不十分。
+
+---
+
+## MCP サーバーの設定
+
+MCP サーバーは `~/.mcp.json` に JSON 形式で設定する。このファイルが Claude Code セッション起動時に読み込まれる。
+
+### ファイル形式
+
+```json
+{
+  "mcpServers": {
+    "<server-name>": {
+      "command": "<起動コマンド>",
+      "args": ["<引数1>", "<引数2>"]
+    }
+  }
+}
+```
+
+### 設定の追加・変更手順
+
+1. `~/.mcp.json` が存在しない場合は新規作成する
+2. 既存の場合は内容を読み取り、`mcpServers` オブジェクトにエントリを追加する
+3. 既存エントリを壊さないよう注意する
+
+```bash
+# 既存ファイルの確認
+cat ~/.mcp.json 2>/dev/null || echo '(not found)'
+```
+
+### よく使う MCP サーバーの設定例
+
+#### Playwright（ブラウザ自動化）
+
+```json
+{
+  "mcpServers": {
+    "playwright": {
+      "command": "npx",
+      "args": ["-y", "@playwright/mcp@latest"]
+    }
+  }
+}
+```
+
+`npx -y` により、未インストールでも自動ダウンロード・実行される。事前の `npm install` は不要。
+
+#### Supabase（データベース）
+
+```json
+{
+  "mcpServers": {
+    "supabase": {
+      "url": "http://<supabase-host>:54321/mcp?read_only=true&features=database,docs"
+    }
+  }
+}
+```
+
+URL ベースの MCP サーバーは `url` フィールドで指定する（`command`/`args` は不要）。
+
+### 注意事項
+
+- `~/.mcp.json` は手動で編集する。Claude Code の設定 UI からは変更できない
+- `npx -y <package>` 形式を使えば、グローバルインストールなしで MCP サーバーを起動できる
+- サーバー名はスキルの `requires.mcp_servers` と一致させる必要がある（例: `playwright`）
+- `claude-settings.json`（`~/.claude/settings.json`）の `mcpServers` に設定しても同様に動作するが、`~/.mcp.json` が推奨
+
+---
+
+## CLI ツールのインストール
+
+スキルが `requires.cli_tools` で宣言したツールは、`which` コマンドでパスが通っていれば検出される。
+
+### パッケージマネージャーの使い分け
+
+| マネージャー | 用途 | インストール先 |
+|-------------|------|---------------|
+| `apt` | OS レベルのツール・ライブラリ | システム全体 (`/usr/bin/` 等) |
+| `npm` | Node.js パッケージ・CLI ツール | `node_modules/` またはグローバル |
+| `npx` | npm パッケージの一時実行 | 一時ディレクトリ（実行後破棄） |
+| `pip` / `pip3` | Python パッケージ | ユーザーディレクトリまたは venv |
+
+### apt（システムパッケージ）
+
+画像処理ツール、テキスト処理ツール、ネットワークツールなど OS レベルのツールに使う。
+
+```bash
+sudo apt update && sudo apt install -y <package-name>
+```
+
+例:
+```bash
+# 画像処理
+sudo apt install -y imagemagick
+
+# JSON 処理
+sudo apt install -y jq
+
+# PDF 処理
+sudo apt install -y poppler-utils
+```
+
+### npm（Node.js CLI ツール）
+
+グローバルインストールで `which` に検出されるようにする。
+
+```bash
+npm install -g <package-name>
+```
+
+例:
+```bash
+# TypeScript コンパイラ
+npm install -g typescript
+
+# Prettier（コードフォーマッター）
+npm install -g prettier
+```
+
+**注意**: MCP サーバーのインストールに `npm install -g` は使わない。MCP サーバーは `~/.mcp.json` に `npx -y` 形式で設定する（前述の MCP サーバー設定を参照）。
+
+### pip / pip3（Python ツール）
+
+```bash
+pip3 install --user <package-name>
+```
+
+`--user` を付けると `~/.local/bin/` にインストールされる。PATH に含まれていることを確認する。
+
+例:
+```bash
+# AWS CLI
+pip3 install --user awscli
+
+# YAML 処理
+pip3 install --user yq
+```
+
+### npx（一時実行）
+
+`npx` はインストールせずに npm パッケージを一時実行する。`cli_tools` の事前チェックでは検出されないため、恒久的に使うツールには `npm install -g` を使うこと。
+
+```bash
+# 一時的な利用（事前チェックでは検出されない）
+npx -y cowsay hello
+
+# 恒久的に必要なら npm install -g を使う
+npm install -g cowsay
+```
+
+---
+
+## インストール後の確認
+
+ツールのインストール後、事前チェックが通るか確認する。
+
+```bash
+# CLI ツールが検出されるか確認
+which <tool-name>
+
+# MCP サーバーが設定されているか確認
+cat ~/.mcp.json | node -e "
+  const cfg = JSON.parse(require('fs').readFileSync('/dev/stdin','utf8'));
+  const servers = cfg.mcpServers || cfg.servers || {};
+  console.log('Configured MCP servers:', Object.keys(servers).join(', ') || '(none)');
+"
+
+# エージェントのキャパビリティキャッシュをクリアして再検出させる
+# (キャパビリティは 5 分間キャッシュされるため、即座に反映したい場合)
+curl -s -X POST "http://localhost:8080/api/capabilities/clear-cache" \
+  -H "Authorization: Bearer $API_TOKEN"
+```

package/docs/task-guides.md

@@ -193,6 +193,19 @@ await reportIssue({ title: '...', body: '...', labels: ['bug'] })
 
 ---
 
+## ツール・MCPサーバーのインストール
+
+スキルが `requires` で宣言している MCP サーバーや CLI ツールが不足している場合は、`~/.minion/docs/environment-setup.md` の手順に従ってインストールする。
+
+主なポイント:
+- **MCP サーバー**: `~/.mcp.json` にエントリを追加する（`npm install` ではなく設定ファイルの編集）
+- **CLI ツール**: `apt`（OS ツール）、`npm install -g`（Node.js ツール）、`pip3 install --user`（Python ツール）を使い分ける
+- **確認**: インストール後 `which <tool>` や `cat ~/.mcp.json` で事前チェックが通るか確認する
+
+詳細は `~/.minion/docs/environment-setup.md` を参照。
+
+---
+
 ## トラブルシューティング
 
 ### HQ APIの仕様がわからない

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geekbeer/minion",
-  "version": "2.53.2",
+  "version": "2.53.3",
   "description": "AI Agent runtime for Minion - manages status and skill deployment on VPS",
   "main": "linux/server.js",
   "bin": {

package/rules/core.md

@@ -92,3 +92,4 @@ Workflow/Routine 実行中は以下も利用可能:
 API仕様やタスク手順の詳細は以下を参照:
 - `~/.minion/docs/api-reference.md` — ローカルAPI・HQ APIの全エンドポイント仕様
 - `~/.minion/docs/task-guides.md` — スキル修正・ワークフロー管理等の手順書
+- `~/.minion/docs/environment-setup.md` — MCPサーバー設定・CLIツールインストール手順