bash-mcp

bash-mcp

一般的な CLI ツール（kubectl、terraform、helm、git、argocd、jq、yq、ripgrep など）をラップし、生のテキスト出力ではなく、構造化された JSON を返す MCP サーバーです。

人間が読みやすい CLI 出力の解析にトークンを浪費し、簡単に失敗してしまう、AI エージェントや LLM を活用したワークフロー向けに設計されています。

構造化データを主に利用するのが Claude であるため、Claude の協力を得て作成されました。

クイックスタート

オプション 1：npx でインストール不要

インストールは不要です。MCP の設定を追加するだけで、初回使用時に npx が取得します。

オプション 2：グローバルインストール

npm install -g @nickw8/bash-mcp

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

git clone https://github.com/nickw8/bash-mcp.git
cd bash-mcp
npm install && npm run build
npm link

セットアップを確認する

bash-mcp をクライアントに接続する前に、組み込みの事前チェックを実行してください。

npx -y @nickw8/bash-mcp --doctor   # or: bash-mcp --doctor (global install)

Node のバージョン、MCP SDK が読み込まれるかどうか、利用可能な CLI（バージョンを含む）、解決された BASH_MCP_MODE を報告します。その後、重大なチェックに失敗した場合（Node のバージョンが古すぎる、または SDK を読み込めない場合）は、ゼロ以外の終了コードで終了します。利用できない CLI は参考情報であり、失敗とは見なされません。--doctor を指定しない場合、通常どおり MCP サーバーが起動します。

Claude Code のセットアップ

Claude Code の設定に bash-mcp を追加します。すべてのプロジェクトに適用する場合（推奨）は ~/.claude/settings.json を、単一のプロジェクトに適用する場合はプロジェクトルートの .claude/settings.json を編集します。

npx を使用する場合（インストール不要）：

{
  "mcpServers": {
    "bash-mcp": {
      "command": "npx",
      "args": ["-y", "@nickw8/bash-mcp"],
      "env": {
        "BASH_MCP_MODE": "readOnly"
      }
    }
  }
}

デフォルトで安全： BASH_MCP_MODE が未設定の場合は readOnly になり、変更を伴う run／batch コマンドがブロックされます。例では分かりやすさのため、明示的に設定しています。信頼できるローカル環境で書き込みを許可するには、BASH_MCP_MODE=off を設定してください。

グローバルインストールを使用する場合：

{
  "mcpServers": {
    "bash-mcp": {
      "command": "bash-mcp",
      "env": {
        "BASH_MCP_MODE": "readOnly"
      }
    }
  }
}

正常に動作していることを確認するには、Claude Code を起動し、ツール一覧に cat、rg、git_status などの bash-mcp ツールが表示されることを確認します。

CLI から追加することもできます。

claude mcp add bash-mcp -e BASH_MCP_MODE=readOnly -- npx -y @nickw8/bash-mcp

エージェントを構造化ツールに誘導する（任意）

サーバーを登録するとツールが使えるようになりますが、エージェントは習慣で生の Bash を使おうとします。これを解決するアセットが 2 つあります。各セッションに自動で読み込まれるルールファイル（~/.claude/rules/bash-mcp-tools.md。ツール一覧を記載）と、PreToolUse(Bash) リダイレクトフックです。次のコマンドで両方をインストールします。

npx -y @nickw8/bash-mcp --install-claude        # copy into ~/.claude
npx -y @nickw8/bash-mcp --install-claude --check # report drift, write nothing

貼り付けるための settings.json フックブロックが出力されます（ルールファイルには設定が不要です。Claude Code が ~/.claude/rules/*.md を自動で読み込みます）。詳細と、クローン後に実行する npm run claude:install による同等の手順については、hooks/README.md を参照してください。--uninstall-claude を実行すると、両方のファイルを削除できます。

または、サーバーとフックを同梱した Claude Code プラグインをインストールします（warn モードでは、BASH_MCP_HOOK=block が設定されていない限りブロックされません）。

/plugin install bash-mcp --marketplace nickw8/bash-mcp

その他のすべてのクライアント（VS Code/Copilot、Codex、汎用 stdio）と、バージョンを固定する方法については、docs/guides/installation.md を参照してください。

Claude Desktop のセットアップ

claude_desktop_config.json（macOS：~/Library/Application Support/Claude/、Windows：%APPDATA%\Claude\）を編集し、同じ mcpServers エントリを追加します。

{
  "mcpServers": {
    "bash-mcp": {
      "command": "npx",
      "args": ["-y", "@nickw8/bash-mcp"],
      "env": {
        "BASH_MCP_MODE": "readOnly"
      }
    }
  }
}

編集後、Claude Desktop を再起動してください。

Cursor のセットアップ

bash-mcp を ~/.cursor/mcp.json（グローバル）または .cursor/mcp.json（プロジェクトごと）に追加します。

{
  "mcpServers": {
    "bash-mcp": {
      "command": "npx",
      "args": ["-y", "@nickw8/bash-mcp"],
      "env": {
        "BASH_MCP_MODE": "readOnly"
      }
    }
  }
}

（グローバルにインストールした場合は、引数なしで "command": "bash-mcp" を使用してください。）MCP 対応クライアントなら、どれでも同じ方法で使用できます。bash-mcp バイナリまたは npx -y @nickw8/bash-mcp を指定してください。

推奨フック

任意で利用できる Claude Code フックは hooks/ にあります。bash-mcp に相当するコマンドがある生のシェルコマンド（git status、kubectl get、cat など）をブロックして、エージェントを構造化ツールに誘導する一方、書き込みコマンド（git commit、kubectl apply など）はそのまま実行できます。BASH_MCP_HOOK=warn にすると、すべてのブロックが警告のみになります。off にするとフックが無効になります。

セットアップについては、docs/runbooks/hooks-setup.md を参照してください。

構造化出力を使う理由

生の CLI ツールは、人間向けのテキストを返します。AI エージェントは、表の解析や列の整列、フィールドの境界の推測にトークンを浪費します。bash-mcp は同じ CLI ツールを実行しますが、型付きスキーマを備えた構造化 JSON を返すため、エージェントは必要なデータだけを取得できます。

# Raw kubectl output: 148 tokens to parse a table
NAME                     READY   STATUS    RESTARTS   AGE
nginx-7c5b8d6c88-abc12  1/1     Running   0          3d

# bash-mcp output: typed, compact, ready to use
{ "name": "nginx-7c5b8d6c88-abc12", "status": "Running", "age": "3d", ... }

測定した節約量については、docs/guides/token-benchmarks.md をご覧ください（例： kubectl describe pod → kube_diagnose_pod ではトークン数が約64%減少します）。

方針：まず構造化ツールを使い、run は最後の手段にする

1. まず構造化ツールを使います。 すべてのラッパーは、エージェントがそのまま利用できる型付き JSON を返します。列数のカウントも、フォーマット変更時の再解析も不要です。
2. 生コマンドを連続して実行するより、診断ツールを優先します。 kube_diagnose_pod、 helm_release_triage、argo_app_health_summary などのツールは、get を実行してから logs を実行し、その両方をもとに推論するのではなく、1回の呼び出しで 運用上の問い に答えます — { status, likelyCauses, suggestedNextCommands, evidence }。
3. run / batch は最後の手段です。 専用のラッパーがないコマンドには、run を使えばスマートな切り詰め処理を適用して実行できます。オプションのフックを使うと、生コマンド相当の処理が呼び出された際に、エージェントを構造化ツールへ積極的に誘導できます。

読み取り専用ツールには MCP の readOnlyHint アノテーションが付いています。run/batch は BASH_MCP_MODE を使って制限できます（設定を参照）。

どのツールを使えばよいですか？

生のコマンドを使うのではなく、目的に合った構造化ツールを選んでください。 list_guidance ツールは、同じインデックスを JSON 形式で返します（intent または category で絞り込めます）。 これにより、エージェントは README を参照せずに適切なツールを選べます。

目的	使用するツール	代わりに使うコマンド
クラッシュまたは失敗している Kubernetes ポッドを診断する	kube_diagnose_pod	kubectl describe pod、kubectl logs
名前空間内の未準備または失敗しているポッドをすべて見つける	kube_pod_failure_summary	kubectl get pods、kubectl get pods | grep
デプロイのロールアウト状態を確認する	kube_deployment_status	kubectl rollout status、kubectl get deployment
最近のクラスターイベントを把握する	kube_events_summary	kubectl get events
Terraform プランの変更内容を要約する	tf_plan_summary	terraform plan、terraform show
PR を作成する前に、現在の機能ブランチを確認する	git_pr_context	git diff、git log、git status
リポジトリ全体の状態を把握する	repo_health_summary	git status、git log --oneline
ファイル全体を読み込まずに構造を確認する	outline	cat (ファイル全体)、cat
大きなファイルの一部を読む	cat	cat (ファイル全体)、sed -n '10,40p'
広範な検索でコンテキストがあふれるのを防ぐ	rg	rg | head
コード内の正確な参照箇所やシンボルを検索する	rg	grep -r、rg
プルリクエストの CI チェックが通過しているか確認する	gh_pr_checks	gh pr checks、gh pr view
CI / GitHub Actions の実行が失敗した理由を確認する	gh_run_failure_summary	gh run view --log-failed、gh run list
GitLab パイプラインまたはマージリクエストのジョブが通過しているか確認する	glab_ci_status	glab ci get、glab ci status
GitLab CI パイプラインが失敗した理由を確認する	glab_pipeline_failure_summary	glab ci trace、glab ci view
Helm リリースが正常でない理由を調査する	helm_release_triage	helm status、helm get values
ArgoCD アプリが正常で同期されているか確認する	argo_app_health_summary	argocd app get、argocd app list
Liquibase の変更履歴ファイルにエラーがないか検証する	liquibase_validate	liquibase validate
保留中の変更セットに対して Liquibase が実行する SQL をプレビューする	liquibase_update_sql	liquibase updateSQL、liquibase updateSQL | grep
データベースにまだ適用されていない Liquibase の変更セットを一覧表示する	liquibase_status	liquibase status --verbose
シェルスクリプトのバグや引用符の問題を検査する	bash_lint	shellcheck、shellcheck -f json1
bats またはシェルのテストスイートを実行する	bash_test	bats、bash test.sh
ツールを呼び出す前に、インストール済みの CLI を確認する	check_environment	which、<tool> --version

ツール

📖 ツールの完全なリファレンス → docs/tools.md — 登録済みツール（入力、出力、およびそれぞれが近似する生のコマンド）から生成されています。 npm run docs:tools で再生成できます。

環境

ツール	説明
check_environment	インストール済みの CLI とそのバージョンを報告し、呼び出す前に適切なツールを選べるようにします。
list_guidance	目的に合った bash-mcp ツールを選べるように、目的から推奨ツールへのインデックスを返します。

ファイルシステム

ツール	説明
ls	ディレクトリ内のファイルを一覧表示します。
tree	ディレクトリ構造をコンパクトなツリー形式で表示します。
du	パスのディスク使用量を表示します。
find_files	名前のパターン、種類、または更新時刻に基づいてファイルを検索します。

検索

ツール	説明
rg	ripgrep でファイルの内容を検索します。
glob	glob パターンに一致するファイルを検索します。

ファイル

ツール	説明
cat	行番号を付け、適切に切り詰めて、1 つ以上のファイルを読み取ります。
outline	ファイルの構造の概要（関数名／クラス名、トップレベルのコメント、インポート）を表示します。

Git

ツール	説明
git_status	構造化された git の状態：ブランチ、ステージ済み／未ステージのファイル、追跡対象外のファイル。
git_log	構造化された git ログ：コミットハッシュ、作成者、日付、メッセージ。
git_diff	構造化された git diff：変更されたファイルと追加／削除行数。
git_branches	git ブランチを一覧表示します。
repo_health_summary	git 作業ツリーの状態を一度の呼び出しで確認します：ブランチ、アップストリームとの差分（先行／遅延）、ステージ済み／未ステージ／追跡対象外のファイル数、最近のコミット、未コミットの diffstat。
git_pr_context	ブランチとベース参照との差分について、PR の説明を作成するためのコミットとファイル変更を収集します：コミット一覧、ステータス付きの変更ファイル、base...head 間の diffstat。
git_diff_content	構造化されたパッチ内容を含む git diff を表示します。

GitHub

ツール	説明
gh_pr_checks	プルリクエストの CI チェックを状態別の件数と、失敗中および保留中のチェックとともに報告します。
gh_run_failure_summary	GitHub Actions の実行を一度の呼び出しで診断します：ステータス、失敗したジョブとステップ、証拠となる失敗ログ内の ##[error] 行。

GitLab

ツール	説明
glab_ci_status	GitLab パイプラインのジョブをステータス別の件数と、失敗中、実行中および保留中のジョブとともに報告します。
glab_pipeline_failure_summary	GitLab パイプラインを一度の呼び出しで診断します：ステータス、失敗したジョブと GitLab が示す失敗理由、証拠となる各失敗ジョブのトレース末尾のスクリプト行。

Kubernetes

ツール	説明
kube_get	Kubernetes リソースを構造化データとして取得します。
kube_logs	Pod のログを取得します。
kube_contexts	利用可能な kubectl コンテキストを一覧表示し、現在のコンテキストを示します。
kube_diagnose_pod	Pod が正常でない理由を一度の呼び出しで診断します。
kube_pod_failure_summary	名前空間内の正常でない Pod を、失敗理由と証拠とともに一覧表示します。Pod ごとに get と describe を実行する代わりに、一度の呼び出しで確認できます。
kube_deployment_status	デプロイメントのロールアウト状態（準備完了／希望レプリカ数、条件）を構造化された診断結果として報告します。
kube_events_summary	生の kubectl get events をスクロールする代わりに、名前空間内の Warning イベントを要約します（理由別にグループ化し、件数順に表示）。

Terraform

ツール	説明
tf_state_list	Terraform の状態にあるリソースを一覧表示します。
tf_show	現在の Terraform の状態を構造化 JSON として表示します。
tf_plan_summary	terraform plan を実行し、変更の構造化された概要（追加／変更／破棄の件数と影響を受けるリソース）を返します。
tf_workspaces	Terraform ワークスペースを一覧表示し、現在のワークスペースを示します。
tf_outputs	Terraform/OpenTofu の出力を [名前, 値] のペアとして一覧表示します。機密扱いの出力は [名前] のみ表示します。
tf_providers	プロジェクトの Terraform/OpenTofu のバージョンと、選択されたプロバイダーのバージョンを一覧表示します。
tf_validate_summary	Terraform/OpenTofu の設定を検証し、診断情報を含む簡潔な合否の概要を返します。
tf_modules_summary	初期化済みの Terraform/OpenTofu プロジェクトで使用されているモジュールを一覧表示します（キー、ソース、バージョン）。
tf_backend_info	初期化済みのプロジェクトで設定されているバックエンドの種類と設定を報告します。

Helm

ツール	説明
helm_list	Helm リリースを、ステータス、チャート、アプリのバージョンとともに一覧表示します。
helm_status	Helm リリースの詳細なステータスを取得します。
helm_values	Helm リリースの計算済みの値を構造化データとして取得します。
helm_release_triage	Helm リリースの状態を一度の呼び出しで診断します：helm status と helm history を組み合わせ、現在のステータス、考えられる原因、推奨される次のコマンド、最近のリビジョンに関する証拠を提示します。

ArgoCD

ツール	説明
argo_apps	同期／ヘルス状態とともに ArgoCD アプリケーションの一覧を取得します。
argo_app_detail	リソースのヘルスを含む、単一の ArgoCD アプリケーションの詳細な状態を取得します。
argo_app_diff	ArgoCD アプリケーションで同期されていない内容を表示します。
argo_app_health_summary	1 回の呼び出しで ArgoCD アプリケーションのヘルスを診断します。全体的な同期／ヘルス状態、考えられる原因、次に実行するコマンドの提案、および根拠となる異常なリソース／状態を返します。

データ処理

ツール	説明
jq	jq 式を使用して JSON をクエリおよび変換します。
yq	yq 式を使用して YAML ファイルをクエリおよび変換します（mikefarah/yq）。

.NET

ツール	説明
dotnet_build	dotnet build を実行し、ファイル、行、列、メッセージ、エラーコードを含む構造化診断情報を返します。
dotnet_test	dotnet test を実行し、成功／失敗／スキップ件数や失敗メッセージなどの構造化された結果を返します。

Liquibase

ツール	説明
liquibase_validate	Liquibase の変更履歴ファイルを検証し、変更セットごとのエラー（ID の重複、チェックサムの不一致）を含む構造化された成功／失敗結果を返します。
liquibase_update_sql	保留中の変更セットに対して Liquibase が実行する SQL（updateSQL）をレンダリングし、SQL Server のバッチ lint 結果を含む、変更セットごとの構造化された要約を返します。
liquibase_status	対象データベースにまだ適用されていない Liquibase の変更セットを、構造化 JSON として一覧表示します。

Node.js

ツール	説明
npm_lint	biome check を実行し、ファイル、行、列、メッセージ、ルールを含む構造化診断情報を返します。
npm_test	vitest または jest（package.json から選択）を実行し、スイート、成功／失敗件数、失敗メッセージなどの構造化されたテスト結果を返します。
npm_typecheck	tsc/tsgo --noEmit を実行し、ファイル、行、列、メッセージ、TS エラーコードを含む構造化された型エラーを返します。

Python

ツール	説明
python_lint	ruff check を実行し、ファイル、行、列、メッセージ、ルールコードを含む構造化診断情報を返します。
python_test	pytest を実行し、スイート、成功／失敗件数、失敗メッセージなどの構造化されたテスト結果を返します。
python_typecheck	mypy を実行し、ファイル、行、列、メッセージ、エラーコードを含む構造化された型エラーを返します。

Shell

ツール	説明
bash_syntax_check	bash -n でシェルスクリプトの構文エラーを確認し、構造化診断情報（ファイル、行、メッセージ）を返します。
bash_lint	shellcheck を実行し、ファイル、行、列、メッセージ、SC ルールコードを含む構造化診断情報を返します。
bash_test	シェルテストスクリプトを実行します。bats の .bats ファイルは --tap で、または通常の .sh ハーネスを実行し、ケースごとの成功／失敗と、TAP または N tests, M failures の出力から解析した要約を含む構造化された結果を返します。形式を認識できない場合は、終了コードのみを返します。

実行

ツール	説明
run	単一のコマンドを実行します。バイナリと引数の配列を指定し、シェルを介さず直接実行するため、文字列内でパイプ、リダイレクト、;／&& は使用できません。スマートな切り詰めを行い、構造化された出力を返します。
run_seq	ラベル付きコマンドを順番に実行し、デフォルトでは最初の失敗時に停止します。
batch	複数のコマンドを並列に実行し、すべての結果を返します。

結果

ツール	説明
result_get	応答の予算によって切り詰められた結果をページ単位で取得します。

すべての tf_* ツールでは、OpenTofu を実行するために binary: "terraform" | "tofu" を指定するか、$TF_BINARY を設定できます。

エージェントのワークフロー例

クラッシュループしている Pod をトリアージします。 実行前 — 生の呼び出しを 3 回行い、推論します。

kubectl get pods -n payments          # find the broken pod
kubectl describe pod api-xyz          # read events/state, infer cause
kubectl logs api-xyz --tail=200       # scroll for the error
# ...agent reasons across all three to guess the next step

実行後 — 構造化された呼び出しを 1 回行います。

kube_diagnose_pod(pod="api-xyz", namespace="payments")
→ { status: "CrashLoopBackOff",
    likelyCauses: ["container exits 1; DB connection refused"],
    suggestedNextCommands: ["kube_logs(pod='api-xyz', container='api')"],
    evidence: ["Restart Count: 12", "BackOff x140 over 30m"] }

機能ブランチをレビューします。 実行前：git log main..HEAD、git diff --stat main...HEAD、 git diff main...HEAD — コマンドを 3 回実行し、手作業で結果をまとめます。実行後：

git_pr_context(base="main")
→ { commits: [...], files: [...], summary: { filesChanged, insertions, deletions } }

操作前に機能を確認します。 which kubectl && kubectl config current-context の代わりに：

check_environment()
→ { kubectl: { installed: true, version: "1.31.2", context: "prod" },
    terraform: { installed: false }, ... }

設定

環境変数

変数	値	デフォルト	効果
BASH_MCP_LOG	error | info | off	error	詳細イベントの JSON ログを stderr に出力します（ツール呼び出しごとに 1 行）。error は失敗した呼び出しのみを記録し、info は成功した呼び出しも記録します。off／silent は無効にします。stdout は常に MCP 専用です。run／batch コマンドは秘匿されます（メタデータのみ）。
BASH_MCP_MODE	readOnly | confirmWrites | off	readOnly	run／batch を制限します。デフォルトの readOnly は、変更を伴うものとして分類されたコマンドをブロックします（confirmWrites も同様です）。適用を無効にするには off（または dangerous）を設定します。信頼できるローカル環境でのみ推奨します。
BASH_MCP_PROFILE	core | development | infrastructure | all	all	登録するツールグループを指定します。ツールが少ないほど、コンテキスト内のスキーマも少なくなります。ツールの検出を参照してください。不明な値を指定すると、起動時にエラーになります。
BASH_MCP_RESPONSE_MODE	auto | summary | compact | full	auto	応答の予算です。結果が切り詰められた場合は retained が含まれ、完全なペイロードは result_get でページ取得できます。full は v4 の動作です。出力規約を参照してください。
BASH_MCP_RESULT_TTL	秒	900	保存された結果を取得可能な期間です。0 にすると保存が無効になります。
BASH_MCP_HOOK	block | warn | off	block（プラグインでは warn）	リダイレクトフックの動作を指定します。
TF_BINARY	terraform | tofu	terraform	すべての tf_* ツールで使用するデフォルトのバイナリです（binary を指定すれば呼び出しごとに上書きできます）。

タイムアウト

各ツールグループには、適切なデフォルトのタイムアウトが設定されています。

• ファイルシステム／検索／git：30 秒
• Kubernetes／Helm／ArgoCD：15 秒
• Terraform の状態：30 秒
• Terraform のプラン：120 秒
• .NET のビルド／テスト：120 秒
• Python の lint：30 秒
• Python のテスト：120 秒
• Python の型チェック：60 秒

コマンドバッファー

すべてのコマンドのデフォルトの出力バッファーは 10 MB です。src/exec.ts でツールごとに上書きできます。

開発

# Install dependencies
npm install

# Run in development mode (auto-reloads)
npm run dev

# Build for production
npm run build

# Start production server
npm start

# Run tests
npm test

# Lint and format
npm run lint
npm run format

アーキテクチャ

src/
  index.ts              # Server entry point — registers tools and starts stdio transport
  exec.ts               # Command execution layer — runs CLI tools via execFile
  tool.ts               # defineTool — wraps registerTool with wide-event logging + error catching
  error.ts              # ToolError taxonomy + classifyError (missing_binary, timeout, ...)
  logger.ts             # Zero-dep structured stderr logger (BASH_MCP_LOG)
  safety.ts             # Command classification + BASH_MCP_MODE gate for run/batch
  format.ts             # Multi-format list output (TSV, columnar, JSON)
  response.ts           # MCP response helpers (ok, okList, err)
  shell.ts              # Shell escaping utilities
  parsers/
    types.ts            # Shared interfaces: Diagnostic, TestResult, TestSuite
    schemas.ts          # Shared Zod (diagnostic, budget fragment, applyBudget)
  tools/
    argocd/argocd.ts    # argo_apps, argo_app_detail, argo_app_diff
    batch/batch.ts      # batch (parallel command execution)
    dotnet/
      dotnet.ts         # dotnet_build, dotnet_test
      parsers/          # MSBuild and TRX output parsers
    file/
      file.ts           # cat (file reading with metadata), outline (structural file outline)
      outline/          # Language-specific outline extractors
    filesystem/
      filesystem.ts     # ls, tree, du, find_files
    git/
      git.ts            # git_status, git_log, git_diff, git_branches
      diff.ts           # git_diff_content (structured patch hunks)
    helm/helm.ts        # helm_list, helm_status, helm_values
    json/json.ts        # jq
    kubernetes/
      kubernetes.ts     # kube_get, kube_logs, kube_contexts
    npm/
      npm.ts            # npm_lint, npm_test, npm_typecheck
      parsers/          # Biome, Vitest, tsc output parsers
    run/run.ts          # run (command execution with smart truncation)
    search/search.ts    # rg, glob
    terraform/
      terraform.ts      # tf_state_list, tf_show, tf_plan_summary, tf_workspaces
    yaml/yaml.ts        # yq

各ツールファイルは、グループ内のすべてのツールを登録する単一の register*Tools(server) 関数をエクスポートします。各ツールは、content（表示用テキスト）と structuredContent（プログラムで利用するための型付き JSON）の両方を返します。

新しいツールの追加

1. 既存のカテゴリ（src/tools/<group>/<group>.ts）に追加するか、新しいカテゴリディレクトリを作成します
2. Zod で入出力スキーマを定義します（読み取り専用ツールには annotations: { readOnlyHint: true } を追加します）
3. #exec の exec() または execJson() を使ってハンドラーを実装し、#response の ok() または err() を返します
4. #tool の defineTool で登録します（詳細イベントのログ記録と統一されたエラー捕捉が注入されます）
5. グループの register*Tools を src/index.ts に組み込みます
6. 同じディレクトリにある *.test.ts ファイルにテストを追加します

import { z } from "zod";
import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { exec } from "#exec";
import { ok, err } from "#response";
import { defineTool } from "#tool";

export function registerMyTools(server: McpServer) {
  defineTool(server, "my_tool", {
    title: "My tool",
    description: "What it does and why structured output helps.",
    inputSchema: {
      path: z.string().describe("Path to operate on"),
    },
    outputSchema: {
      result: z.string(),
    },
    annotations: { readOnlyHint: true },
  }, async ({ path }) => {
    const result = await exec("mytool", ["--json", path]);

    if (result.exitCode !== 0) {
      return err(result.stderr, { result: "" });
    }

    return ok({ result: result.stdout.trim() });
  });
}

詳しい手順については、docs/guides/adding-tools.mdを参照してください。

前提条件

各ツールグループを動作させるには、対応する次の CLI ツールがインストールされている必要があります。

• 常に必要：Node.js >= 20
• ファイルシステム／検索：ls、tree、find、du、rg（ripgrep）
• Git：git
• Kubernetes：kubectl
• Terraform／OpenTofu：terraform または tofu
• Helm：helm
• ArgoCD：argocd
• JSON：jq
• YAML：yq（mikefarah/yq）
• .NET：dotnet（.NET SDK）
• Liquibase：liquibase
• Python：ruff（lint）、mypy（型チェック）、pytest（テスト）

基盤となる CLI がインストールされていない場合、ツールはエラーを適切に返します。

ライセンス

Apache-2.0