click-mcp

click-mcp

Click アプリケーションに Model Context Protocol（MCP）のサポートを追加し、AI エージェントが CLI ツールを操作できるようにする Python ライブラリです。

概要

click-mcp は、Click コマンドを MCP ツールに変換するシンプルなデコレーターを提供します。これにより、AI エージェントが CLI アプリケーションをプログラムから検出し、操作できるようになります。

Model Context Protocol（MCP） は、AI エージェントがツールやアプリケーションと構造化された方法でやり取りするためのオープン標準です。

主な機能

• シンプルな @click_mcp デコレーター構文
• Click コマンドを MCP ツールに自動変換
• ネストされたコマンドグループをサポート
• 位置引数をサポート
• 簡単に統合できる、stdio ベースの MCP サーバー

インストール

pip install click-mcp

基本的な使い方

import click
from click_mcp import click_mcp

@click_mcp(server_name="my-cli-app")
@click.group()
def cli():
    """Sample CLI application."""
    pass

@cli.command()
@click.option('--name', required=True, help='Name to greet')
def greet(name):
    """Greet someone."""
    click.echo(f"Hello, {name}!")

if __name__ == '__main__':
    cli()

MCP サーバーを実行すると、Click コマンドが MCP ツールに変換されます。

• コマンド greet は MCP ツール greet になります
• ネストされたコマンドにはドット記法が使われます（例：users.create）

MCP 経由でコマンドを呼び出すには、次のようなリクエストを送信します。

{
  "type": "invoke",
  "tool": "greet",
  "parameters": {
    "name": "World"
  }
}

MCP サーバーを起動するには、次のようにします。

$ python my_app.py mcp

高度な使い方

MCP コマンド名のカスタマイズ

デフォルトでは、click-mcp は CLI アプリケーションに mcp コマンドを追加します。command_name パラメーターを使って、この名前をカスタマイズできます。

@click_mcp(command_name="start-mcp")
@click.group()
def cli():
    """Sample CLI application with custom MCP command name."""
    pass

この設定では、次のようにして MCP サーバーを起動します。

$ python my_app.py start-mcp

次のような場合に便利です。

• 名前「mcp」が既存のコマンドと競合する場合
• より説明的なコマンド名を付けたい場合
• 特定のコマンド名を想定する AI エージェントと統合する場合

MCP サーバー名のカスタマイズ

クライアントに通知する MCP サーバー名もカスタマイズできます。

@click_mcp(server_name="my-custom-tool")
@click.group()
def cli():
    """Sample CLI application with custom server name."""
    pass

次のような場合に便利です。

• ツールにより説明的な名前を付けたい場合
• サーバー名を識別に使用するシステムと統合する場合
• MCP に対応した複数のアプリケーションを区別したい場合

ネストされたコマンドグループの操作

click-mcp はネストされたコマンドグループをサポートします。サブコマンドを含む複雑な CLI 構造の場合、すべてのコマンドが MCP ツールとして公開されます。

@click_mcp
@click.group()
def cli():
    """Main CLI application."""
    pass

@cli.group()
def users():
    """User management commands."""
    pass

@users.command()
@click.option('--username', required=True)
def create(username):
    """Create a new user."""
    click.echo(f"Creating user: {username}")

@users.command()
@click.argument('username')
def delete(username):
    """Delete a user."""
    click.echo(f"Deleting user: {username}")

MCP ツールとして公開されると、ネストされたコマンドは完全なパスを使ったドット記法（例：「users.create」と「users.delete」）で利用できます。

位置引数の操作

Click は @click.argument() を使った位置引数をサポートします。これらを MCP ツールに変換すると、スキーマ内では名前付きパラメーターとして表現されます。

@cli.command()
@click.argument('source')
@click.argument('destination')
@click.option('--overwrite', is_flag=True, help='Overwrite destination if it exists')
def copy(source, destination, overwrite):
    """Copy a file from source to destination."""
    click.echo(f"Copying {source} to {destination}")

このコマンドは、次のスキーマを持つ MCP ツールに変換されます。

{
  "type": "object",
  "properties": {
    "source": {
      "description": "",
      "schema": { "type": "string" },
      "required": true
    },
    "destination": {
      "description": "",
      "schema": { "type": "string" },
      "required": true
    },
    "overwrite": {
      "description": "Overwrite destination if it exists",
      "schema": { "type": "boolean" }
    }
  },
  "required": ["source", "destination"]
}

引数の位置引数としての性質は、click-mcp によって内部的に処理されます。コマンドを呼び出す際は、名前付きパラメーターを使用できます。

{
  "type": "invoke",
  "tool": "copy",
  "parameters": {
    "source": "file.txt",
    "destination": "/tmp/file.txt",
    "overwrite": true
  }
}

MCP サーバーは、Click コマンドの実行時にこれらを正しく位置引数に変換します。

copy file.txt /tmp/file.txt --overwrite

コマンドエラーの処理

Click コマンドが例外を発生させると、click-mcp はエラーを捕捉し、MCP レスポンスの一部として返します。これにより、AI エージェントはエラーを適切に処理できます。

@cli.command()
@click.option('--filename', required=True)
def process(filename):
    """Process a file."""
    try:
        with open(filename, 'r') as f:
            content = f.read()
        click.echo(f"Processed file: {filename}")
    except FileNotFoundError:
        raise click.UsageError(f"File not found: {filename}")

ファイルが存在しない場合、AI エージェントはエラーメッセージを受け取り、それをユーザーに提示したり、問題を修正するための処理に利用したりできます。

開発

セットアップ

リポジトリをクローンし、Hatch をインストールします。

git clone https://github.com/aws/click-mcp.git
cd click-mcp
pip install hatch

テスト

Hatch を使ってテストを実行します。

# Run all tests
hatch run test

# Run tests with coverage
hatch run cov

コードのフォーマット

Black を使ってコードをフォーマットします。

# Format code
hatch run format

# Check formatting
hatch run check-format

リント

Ruff を使ってリントチェックを実行します。

hatch run lint

型チェック

MyPy を使って型チェックを実行します。

hatch run typecheck

すべてのチェックを実行

すべてのチェック（フォーマット、リント、型チェック、テスト）を実行します。

hatch run check-all

ビルド

パッケージをビルドします。

hatch run build

ドキュメント

ドキュメントを生成します。

hatch run docs

関連リソース

• Model Context Protocol (MCP) の仕様
• Click のドキュメント
• MCP Tools Registry - MCP 互換ツールのコレクション

ライセンス

MIT