Claude Code パワーツール

# Claude Code パワーツール

Hook、ヘッドレス実行、MCP統合で、Claude Codeをプログラム可能なワークフローエンジンに変えます。

## このプラグインできること

このプラグインは3つの composable な機能を組み合わせます：

- **Hook** — ツール呼び出し（PreToolUse / PostToolUse）を横取りして、ルールを強制したり、出力を検証したり、副作用をトリガーしたりできます
- **ヘッドレス** — バッチ処理、CI/CD、スクリプトのために `claude -p` でClaude Codeを非インタラクティブに実行
- **MCP** — Claudeに外部システム（データベース、API、メッセージング）へのアクセスを提供するModel Context Protocolサーバーを構築

この3つの部品はogether**: hooksは*Claudeが何をするか*を制御し、ヘッドレスは*いつどのように実行するか*を制御し、MCPは*何にアクセスできるか*を制御します。

## 完全な例：自動コードレビューパイプライン

チームでは、すべてのPRに自動レビューを実施し、結果をSlackに投稿し、違反をブロックしたいと考えています。

### ステップ1: MCPサーバー — 外部システムに接続

Slack投稿とGitHub PRデータを公開するMCPサーバーを構築します：

```typescript
// review-mcp/server.ts
const server = new McpServer({ name: "review-tools" });

server.tool("post_slack", { channel: z.string(), message: z.string() },
  async ({ channel, message }) => {
    await slack.chat.postMessage({ channel, text: message });
    return { content: [{ type: "text", text: "Posted" }] };
  }
);

server.tool("get_pr_diff", { pr: z.number() },
  async ({ pr }) => {
    const diff = await octokit.pulls.get({ owner, repo, pull_number: pr });
    return { content: [{ type: "text", text: diff.data.body }] };
  }
);
```

登録: `claude mcp add review-tools -- node review-mcp/server.ts`

### ステップ2: ヘッドレス — CIでレビューを実行

```yaml
# .github/workflows/review.yml
- name: AI Code Review
  run: |
    claude -p "Review PR #${{ github.event.pull_request.number }}.       Use get_pr_diff to fetch changes, analyze for bugs and style issues,       then post_slack the summary to #code-review."       --allowedTools "mcp__review-tools__post_slack,mcp__review-tools__get_pr_diff"       --output-format json > review-result.json
```

### ステップ3: Hook — ガードレールを強制

```json
// .claude/settings.json
{
  "hooks": {
    "PreToolUse": [{
      "matcher": "mcp__review-tools__post_slack",
      "hooks": [{
        "type": "command",
        "command": "python3 validate_slack.py "$TOOL_INPUT""
      }]
    }]
  }
}
```

HookスクリプトはSlackメッセージがチームのフォーマットルールに従っていることを確認します。ゼロ以外の終了でツール呼び出しがブロックされます。

**結果:** PRがヘッドレスClaudeをトリガー → ClaudeがMCP経由でdiffを取得 → コードをレビュー → Slackに投稿（Hookで検証） — 完全自動化、完全監査可能です。

## リスク境界

### Hook

- Hookは*Claudeのデフォルト動作を変更します*。バグのあるPreToolUse hookは正規のツール呼び出しをサイレントにブロックする可能性があります。デプロイ前に必ず分離環境でテストしてください。
- Hookスクリプトはシェル権限で実行されます。サニタイズせずに信頼できない入力をhookコマンドに直接パイピングしないでください。
- Hookは高速にしてください（2秒未満）。遅いHookはインタラクティブ体験を低下させます。

### ヘッドレスモード

- `--dangerously-skip-permissions`はすべての安全プロンプトを削除します。ロックダウンされた権限を持つ信頼されたCI環境でのみ使用してください。
- ヘッドレス実行にはループ内の人間はいません。`--allowedTools`で許可ツールを明示的にスコープして、意図しないアクションを防ぎます。
- 出力は大きくなる可能性があります。パイプラインでは常に`--output-format json`を設定し、構造化された結果をパースしてください。

### MCPサーバー

- MCPサーバーは独自の権限を持つ別のプロセスとして実行されます。スコープが不適切なサーバーは機密データを公開したり、破壊的な操作を許可したりする可能性があります。
- ツールハンドラーでは常に入力を検証してください。Claudeが生成したパラメータは安全である保証はありません。
- トランスポートレベルの分離を使用してください：本番デプロイではMCPサーバーをコンテナまたは制限付きユーザーアカウントで実行してください。
- エラーは適切に処理してください — 会話中にMCPサーバーがクラッシュすると、再起動するまでClaudeはそのツールにアクセスできなくなります。