click-mcp

click-mcp

一个 Python 库，可为 Click 应用添加模型上下文协议（MCP）支持，让 AI Agent 能够与命令行工具交互。

概述

click-mcp 提供了一个简单的装饰器，可将 Click 命令转换为 MCP 工具。这使 AI Agent 能够以编程方式发现并与命令行应用交互。

模型上下文协议（MCP）是一种开放标准，支持 AI Agent 以结构化方式与工具和应用交互。

主要功能

• 简洁的 @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 会向你的命令行应用添加一个 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 Agent 集成

自定义 MCP 服务名称

你还可以自定义向客户端报告的 MCP 服务名称：

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

以下情况可能适合使用此功能：

• 你想为工具提供更具描述性的名称
• 你要与使用服务名称进行识别的系统集成
• 你想区分不同的启用 MCP 的应用

使用嵌套命令组

click-mcp 支持嵌套命令组。对于包含子命令的复杂命令行结构，所有命令都会作为 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
  }
}

执行 Click 命令时，MCP 服务会正确地将这些参数转换为位置参数：

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

处理命令错误

当 Click 命令引发异常时，click-mcp 会捕获错误，并将其作为 MCP 响应的一部分返回。这使 AI Agent 能够妥善处理错误：

@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 Agent 会收到错误消息，可将其展示给用户或据此采取纠正措施。

开发

设置

克隆代码仓库并安装 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 工具注册表 - MCP 兼容工具的集合

许可证

MIT