关键词

串口控制物联网硬件交互自然语言控制AI赋能

使用说明

项目简介

MCP2Serial 是一个基于 Model Context Protocol (MCP) 的服务器实现，旨在连接物理世界的串口设备与 AI 大模型。它允许用户通过自然语言指令，经由 AI 大模型理解和处理后，转化为串口命令控制硬件设备，实现智能物联网应用。

主要功能点

  • 串口通信桥梁: 建立 AI 大模型与串口设备之间的通信链路。
  • MCP 协议支持: 完整实现了 MCP 协议，可以作为 MCP 服务器与任何兼容 MCP 协议的客户端（如 Claude Desktop, Cline）进行交互。
  • 资源管理: 虽然仓库描述中没有明确资源管理，但 MCP 服务器本身具备资源管理能力，可以预见未来会支持资源管理。
  • 工具调用: 通过定义 'commands'，将串口命令封装为 MCP 工具，允许 LLM 客户端调用这些工具来控制串口设备。
  • Prompt 模板: 通过 'commands' 中的 'prompts' 字段，为每个工具定义了自然语言提示词，优化 LLM 的指令生成和工具调用。
  • 灵活配置: 通过 'config.yaml' 配置文件，用户可以自定义串口参数、命令格式和提示词，适应不同的硬件设备和应用场景。
  • 多客户端支持: 兼容多种实现了 MCP 协议的客户端，如 Claude Desktop, Continue, Cline, Zed, Sourcegraph Cody, Firebase Genkit。
  • 多种 AI 模型支持: 支持云端和本地多种 AI 模型，如 OpenAI, Claude, Gemini, LM Studio, Ollama 等。

安装步骤

  1. 环境准备: 确保已安装 Python 3.11 或更高版本。推荐使用 'uv' 包管理器（仓库提供了安装 'uv' 的脚本）。
  2. 下载安装脚本: 根据你的操作系统（Windows, macOS, Ubuntu/Raspberry Pi），下载对应的安装脚本 ('install.py', 'install_macos.py', 'install_ubuntu.py')。
  3. 运行安装脚本: 在终端或命令提示符中，导航到脚本所在目录，并执行 'python install.py' (或对应的 macOS/Ubuntu 脚本)。安装脚本会自动检查环境、安装依赖、创建配置文件和配置 Claude 桌面版 (如果已安装)。
  4. 手动安装 (可选): 如果安装脚本无法正常工作，可以参考 README 中的 "手动分步安装依赖" 部分，手动安装 'uv' 和其他依赖。

服务器配置

MCP 服务器配置是为 MCP 客户端准备的，用于告知客户端如何启动和连接 MCP2Serial 服务器。以下是配置示例，你需要将这段 JSON 配置添加到你的 MCP 客户端（如 Claude Desktop 或 Cline）的配置文件中。

基础配置 (使用默认配置文件 'config.yaml'):

{
    "mcpServers": {
        "mcp2serial": {
            "command": "uvx", // 启动命令，这里使用 uvx 运行 mcp2serial
            "args": [
                "mcp2serial"  // 命令参数，这里指定运行 mcp2serial 服务
            ]
        }
    }
}

指定配置文件 (例如使用 'Pico_config.yaml'): 如果你想使用不同的配置文件，例如 'Pico_config.yaml'，可以使用 '--config' 参数指定配置文件名 (不需要添加 '_config.yaml' 后缀)。

{
    "mcpServers": {
        "mcp2serial": {
            "command": "uvx",
            "args": [
                "mcp2serial",
                "--config",  // 指定配置文件的参数
                "Pico"      // 配置文件名，对应 Pico_config.yaml
            ]
        }
    }
}

注意:

  • '"mcpServers"' 是客户端配置的固定字段，用于定义 MCP 服务器列表。
  • '"mcp2serial"' 是你为该 MCP 服务器定义的服务名称，可以自定义，但在客户端配置中保持一致即可。
  • '"command": "uvx"' 假设你的环境中 'uvx' 命令可用，如果不行，可以尝试使用 'uv run mcp2serial' 或者 'python src/mcp2serial/server.py' (根据你的安装方式和环境调整)。
  • '"args"' 是传递给 'command' 的参数列表。
  • 修改客户端配置后，通常需要重启客户端软件才能生效。

基本使用方法

  1. 硬件连接: 将你的串口设备通过 USB 连接到电脑，并记录设备的 COM 端口号（Windows）或设备路径（macOS/Linux）。
  2. 配置 'config.yaml': 根据你的硬件设备，编辑 'config.yaml' 文件，配置正确的串口端口号 ('serial.port') 和波特率 ('serial.baud_rate')。你也可以在 'commands' 节点下定义自定义的串口命令和对应的自然语言提示词。
  3. 启动 MCP2Serial 服务器: 在终端或命令提示符中，激活 Python 虚拟环境 (如果创建了虚拟环境)，然后运行命令 'uvx mcp2serial' (或 'uv run mcp2serial' 或 'python src/mcp2serial/server.py'，取决于你的配置)。
  4. 配置 MCP 客户端: 将上面提供的 JSON 配置添加到你的 MCP 客户端（如 Claude Desktop, Cline）的配置文件中，并确保服务名称、启动命令和参数与你的实际配置一致。
  5. 在 MCP 客户端中使用: 启动你的 MCP 客户端，它应该能够自动连接到 MCP2Serial 服务器。你可以在客户端中使用自然语言指令，例如 "把 PWM 调到 50%"，客户端会将指令发送给 MCP2Serial 服务器，服务器解析指令并转换为串口命令发送给硬件设备，从而控制硬件。

示例命令配置 ('config.yaml' 中的 'commands' 节点):

commands:
  set_pwm:  # 命令 ID，用于在 MCP 客户端中调用
    command: "PWM {frequency}\n"  # 实际发送给串口的命令，{frequency} 是占位符，会被客户端传入的参数替换
    need_parse: false  # 是否需要解析串口响应，这里设置为 false 表示不需要，只检查是否收到 "OK" 开头的响应
    prompts: # 自然语言提示词，用于引导 LLM 生成调用该工具的指令
      - "把PWM调到{value}"
      - "Set PWM to {value}%"

注意事项

  • 首次运行 'mcp2serial' 时，可能会自动下载依赖包。
  • 确保串口设备已正确连接，并且在 'config.yaml' 中配置了正确的串口端口号。
  • 如果使用真实串口，请确保当前用户具有串口设备的读写权限。
  • 可以通过修改 'config.yaml' 文件来扩展和自定义串口命令，以适应不同的硬件设备和应用场景。
  • 详细配置说明和 API 文档可以参考仓库中的 'docs' 目录。

信息

分类

桌面与硬件

访问项目