使用说明

项目简介

Click-clack 是一款便捷的工具，旨在简化将现有的 Python Click 命令行脚本集成到 LLM 应用中的过程。它能够自动发现并封装项目目录及其子目录下的所有 Click 命令行接口 (CLI)，并将它们以 MCP (Model Context Protocol) 服务器的形式暴露出来。这意味着你可以使用支持 MCP 协议的 LLM 客户端（例如 Claude Desktop）直接调用和执行你的 Python 脚本，从而扩展 LLM 的功能边界。

主要功能点

自动化工具发现: 自动扫描指定目录及其子目录，查找并识别使用 '@click.command()' 装饰器定义的 Python Click 命令行工具。
MCP 服务器: 将发现的 Click 命令行工具包装成符合 MCP 协议的工具服务，可以通过 JSON-RPC 协议与客户端通信。
参数自动映射: 自动解析 Click 命令的参数类型（如字符串、整数、布尔值、枚举、文件路径等），并将其转换为 MCP 工具所需的参数格式。
标准输出捕获: 执行 Click 命令行工具时，自动捕获其标准输出和标准错误输出，并作为 MCP 工具的响应返回给客户端。
简易UI (可选): 除了 MCP 服务器功能，Click-clack 还提供一个基于 Marimo 框架的简易 Web UI，方便用户在浏览器中直接运行和测试这些 Click 命令（非 MCP 功能，但方便本地调试）。

安装步骤

确保已安装 Python 虚拟环境: 推荐在虚拟环境中安装 Click-clack，避免与全局 Python 环境冲突。如果尚未创建，请先创建并激活虚拟环境。例如，使用 'venv':

python3 -m venv .venv
source .venv/bin/activate  # 或 .venv\Scripts\activate (Windows)

安装 Click-clack: 使用 pip 安装 Click-clack 包：

pip install click-clack

服务器配置

为了让 MCP 客户端（如 Claude Desktop）连接到 Click-clack MCP 服务器，你需要配置客户端的服务器设置。以下是 Claude Desktop 客户端的 'claude_desktop_config.json' 配置文件示例。你需要根据你的实际情况进行修改。

{
    "mcpServers": {
        "click_clack_server_name": {  //  MCP 服务器的名称，可以自定义，在客户端中用于标识该服务器
            "command": "uv",   //  或者 "python",  启动 MCP 服务器的命令，这里假设你已安装 uv 或使用 python
            "args": [        //  启动命令的参数列表
                "run",      //  如果 command 是 "uv"，则需要 "run" 参数
                "--directory",  //  指定工作目录参数
                "/path/to/directory/with/your/click/commands",  //  **[请替换为你的 Click 命令行脚本所在的目录的绝对路径]**  例如："/Users/yourname/my_project/scripts"
                "--",       //  分隔 uv 参数和 click-clack 参数
                "click-clack",  //  运行 click-clack 的命令
                "--mcp",      //  **[必须添加]**  指定以 MCP 服务器模式运行 Click-clack
                "--module-path", //  指定模块路径参数
                "/path/to/directory/with/your/click/commands"   // **[请替换为你的 Click 命令行脚本所在的目录的绝对路径，与上面目录路径保持一致]**
            ]
        }
    }
}

配置参数说明:

'"click_clack_server_name"': 你为这个 MCP 服务器自定义的名称，在 Claude Desktop 客户端中会显示这个名称。
'"command"': 启动 Click-clack MCP 服务器的命令。通常是 'uv run' (如果你全局安装了 'uv' 并使用 'uv' 管理项目) 或者 'python' (如果你直接使用 'python' 运行)。
'"args"': 传递给启动命令的参数列表。
- '"--directory", "/path/to/directory/with/your/click/commands"': [重要] 指定 Click-clack 扫描 Click 命令的根目录。你需要将 '/path/to/directory/with/your/click/commands' 替换为你实际存放 Click 命令行脚本的目录的绝对路径。
- '"click-clack", "--mcp", "--module-path", "/path/to/directory/with/your/click/commands"': 这些是 Click-clack 自身的命令和参数，'"--mcp"' 标志指示 Click-clack 以 MCP 服务器模式运行，'"--module-path"' 再次指定模块搜索路径，需要与 '--directory' 参数指向同一目录。

注意:

请确保将 '/path/to/directory/with/your/click/commands' 替换为你 Click 脚本所在的实际目录的绝对路径。
如果你的项目依赖于特定的 Python 包，请确保在运行 'click-clack' 前已在虚拟环境中安装这些依赖。
如果使用 'uv'，请确保已全局安装 'uv'，并且你的 Click 命令所在的目录是一个有效的 'uv' 项目（已运行 'uv init'）。

基本使用方法

启动 MCP 服务器: 配置好 'claude_desktop_config.json' 后，当 Claude Desktop 客户端启动时，它应该会自动尝试连接到 Click-clack MCP 服务器。或者，你也可以在命令行手动启动 Click-clack MCP 服务器：

source .venv/bin/activate  # 激活虚拟环境 (如果尚未激活)
cd /path/to/directory/with/your/click/commands  # **[切换到你的 Click 脚本所在目录]**
click-clack --mcp --module-path .  #  在当前目录启动 MCP 服务器

在 MCP 客户端中使用: 在 Claude Desktop 或其他支持 MCP 协议的客户端中，你应该能看到名为 '"click_clack_server_name"' (或你在配置文件中设置的名称) 的服务器。展开该服务器，你将看到 Click-clack 自动发现的 Click 命令行工具列表。
调用工具: 选择你想使用的工具，客户端会根据 Click 命令的参数自动生成输入表单。填写参数值后，点击执行按钮，客户端会将请求发送到 Click-clack MCP 服务器执行相应的 Click 命令，并将命令的输出结果返回显示在客户端。

现在，你就可以利用 Click-clack 将你的 Python 命令行工具无缝集成到 LLM 工作流中，通过自然语言指令驱动执行各种自动化任务。

关键词