MCPShell

MCPShell

MCPShell は、LLM が Model Context Protocol（MCP） を通じて コマンドラインツールを安全に実行できるようにするツールです。 LLM とオペレーティングシステムのコマンドの間に、安全なブリッジを提供します。

特長

• 柔軟なコマンド実行：あらゆるシェルコマンドを MCP ツールとして実行できます。 テンプレートを使ってパラメーターを置換できます。
• 設定ベースのツール定義：パラメーター、制約、出力形式を指定して、YAML でツールを定義できます。
• 制約によるセキュリティ：実行前に CEL 式を使ってツールのパラメーターを検証できます。また、コマンド実行に使用するサンドボックス環境も任意で利用できます。
• MCP ツールの迅速なプロトタイピング：シェルコードを追加するだけで、LLM で MCP ツールとして使用できます。
• 簡単な統合：MCP プロトコルをサポートするあらゆる LLM クライアント（Cursor、VSCode、Witsy など）で動作します。

クイックスタート

Cursor（またはほかの MCP クライアント）に、ハードディスクの容量に関する問題を調べてもらいたいとします。

1. ツールを定義する設定ファイル /my/example.yaml を作成します。

   mcp:
     description: |
       Tool for analyzing disk usage to help identify what's consuming space.
     run:
       shell: bash
     tools:
       - name: "disk_usage"
         description: "Check disk usage for a directory"
         params:
           directory:
             type: string
             description: "Directory to analyze"
             required: true
           max_depth:
             type: number
             description: "Maximum depth to analyze (1-3)"
             default: 2
         constraints:
           - "directory.startsWith('/')"  # Must be absolute path
           - "!directory.contains('..')"  # Prevent directory traversal
           - "max_depth >= 1 && max_depth <= 3"  # Limit recursion depth
           - "directory.matches('^[\\w\\s./\\-_]+$')"  # Only allow safe path characters, prevent command injection
         run:
           command: |
             du -h --max-depth={{ .max_depth }} {{ .directory }} | sort -hr | head -20
         output:
           prefix: |
             Disk Usage Analysis (Top 20 largest directories):
   

   より高度で便利な例については、examples ディレクトリをご覧ください。 kubectl を使って、LLM に Kubernetes クラスターの情報を知らせたい場合や、 AWS CLI コマンドを実行させたい場合にも利用できます。

2. Cursor（または MCP をサポートするほかの LLM クライアント）で MCP サーバーを設定します。

   たとえば Cursor では、.cursor/mcp.json を作成します。

   {
       // you need the "go" command available
       "mcpServers": {
           "mcp-cli-examples": {
               "command": "go",
               "args": [
                  "run", "github.com/inercia/[email protected]",
                  "mcp", "--tools", "/my/example.yaml",
                  "--logfile", "/some/path/mcpshell/example.log"
               ]
           }
       }
   }
   

   相対パスを使い、.yaml 拡張子を省略することもできます。

   {
       "mcpServers": {
           "mcp-cli-examples": {
               "command": "go",
               "args": [
                  "run", "github.com/inercia/[email protected]",
                  "mcp", "--tools", "example",
                  "--logfile", "/some/path/mcpshell/example.log"
               ]
           }
       }
   }
   

   この場合、ツールのディレクトリ（デフォルトでは ~/.mcpshell/tools/）内にある example.yaml が検索されます。

   Cursor または Visual Studio Code の設定方法について、詳しくはこちらをご覧ください。 MCP をサポートするほかの LLM も、同様の方法で設定できます。

3. MCP クライアントが更新されていることを確認します（Cursor は初回は自動で認識しますが、設定ファイルを変更した場合は更新が必要です）。

4. 新しいツールで回答できる質問を LLM に尋ねます。たとえば、 「ハードディスクの容量が足りなくなってきました。原因を調べてもらえますか？」 と尋ねてみましょう。

使用方法と設定

すべてのコマンドについては、こちらのドキュメントをご覧ください。

設定ファイルでは、こちらで定義されている YAML 形式を使用します。 例についてはこのディレクトリをご覧ください。

MCPShell をコンテナーや Kubernetes にデプロイする方法については、コンテナーのデプロイガイドをご覧ください。

エージェントモード

LLM をツールに直接接続する AI エージェント機能については、 Don プロジェクトをご覧ください。Don には次の機能があります。

• MCP クライアントを別途必要としない、LLM への直接接続
• RAG（検索拡張生成）のサポート
• マルチエージェントアーキテクチャ
• MCPShell のツール設定形式を使用

セキュリティに関する考慮事項

こう考えるかもしれません。 「この AI は大きなファイルをすべて見つけるのに役立った。ファイルを削除するツールも作ったらどうだろう？」 それはやめてください！

• ツールの範囲は読み取り専用の操作に限定し、LLM に変更を加える権限を与えないでください。
• 制約を使って、コマンド実行に安全なパラメーターだけを使用するよう制限してください。
• コマンドの実行にはサンドボックス環境の使用を検討してください。
• すべてのコマンドテンプレートを確認し、インジェクションの脆弱性がないか調べてください。
• 外部に公開しても安全なツールだけを公開してください。
• 以上すべてを守ってください！

このソフトウェアを使用する前に、セキュリティに関する考慮事項のドキュメントをお読みください。

貢献

貢献を歓迎します！開発ガイドをご覧ください。 GitHub で issue を作成するか、プルリクエストを送信してください。

ライセンス

このプロジェクトは MIT License の下でライセンスされています。詳細は LICENSE ファイルをご覧ください。