click-mcp

一个 Python 库，通过模型上下文协议 (MCP) 支持扩展 Click 应用程序，允许 AI 代理与 CLI 工具交互。

概述

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

模型上下文协议 (MCP) 是一个开放标准，供 AI 代理以结构化的方式与工具和应用程序交互。

主要特性

• 简单的 @click_mcp 装饰器语法
• 自动将 Click 命令转换为 MCP 工具
• 支持嵌套命令组
• 基于 Stdio 的 MCP 服务器，易于集成

安装

pip install click-mcp

基本用法

import click
from click_mcp import click_mcp

@click_mcp
@click.group()
def cli():
    """示例 CLI 应用程序。"""
    pass

@cli.command()
@click.option('--name', required=True, help='要问候的名字')
def greet(name):
    """问候某人。"""
    click.echo(f"你好，{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():
    """具有自定义 MCP 命令名称的示例 CLI 应用程序。"""
    pass

使用此配置，您将使用以下命令启动 MCP 服务器：

$ python my_app.py start-mcp

这在以下情况下很有用：

• 名称 "mcp" 与现有命令冲突
• 您想要一个更具描述性的命令名称
• 您正在与期望特定命令名称的特定 AI 代理集成

使用嵌套命令组

click-mcp 支持嵌套命令组。 当您有一个具有子命令的复杂 CLI 结构时，所有命令都将作为 MCP 工具公开：

@click_mcp
@click.group()
def cli():
    """主 CLI 应用程序。"""
    pass

@cli.group()
def users():
    """用户管理命令。"""
    pass

@users.command()
@click.option('--username', required=True)
def create(username):
    """创建一个新用户。"""
    click.echo(f"正在创建用户：{username}")

@users.command()
@click.argument('username')
def delete(username):
    """删除一个用户。"""
    click.echo(f"正在删除用户：{username}")

当作为 MCP 工具公开时，嵌套命令将使用点表示法（例如，“users.create”和“users.delete”）以其完整路径提供。

处理命令错误

当 Click 命令引发异常时，click-mcp 会捕获该错误并将其作为 MCP 响应的一部分返回。 这允许 AI 代理优雅地处理错误：

@cli.command()
@click.option('--filename', required=True)
def process(filename):
    """处理一个文件。"""
    try:
        with open(filename, 'r') as f:
            content = f.read()
        click.echo(f"已处理文件：{filename}")
    except FileNotFoundError:
        raise click.UsageError(f"未找到文件：{filename}")

如果该文件不存在，AI 代理将收到一条错误消息，它可以将其呈现给用户或用于采取纠正措施。

开发

设置

克隆存储库并安装 Hatch：

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

测试

使用 Hatch 运行测试：

# 运行所有测试
hatch run test

# 运行带有覆盖率的测试
hatch run cov

代码格式化

使用 Black 格式化代码：

# 格式化代码
hatch run format

# 检查格式化
hatch run check-format

代码检查

使用 Ruff 运行代码检查：

hatch run lint

类型检查

使用 MyPy 运行类型检查：

hatch run typecheck

运行所有检查

运行所有检查（格式化、代码检查、类型检查和测试）：

hatch run check-all

构建

构建包：

hatch run build

文档

生成文档：

hatch run docs

相关资源

• 模型上下文协议 (MCP) 规范
• Click 文档
• MCP 工具注册表 - MCP 兼容工具的集合

许可证

MIT