MCP 服务器

MCP Arduino Server (mcp-arduino-server)

Volt23

开发者工具

访问服务器

README

MCP Arduino 服务器 (mcp-arduino-server)

用于 Arduino CLI 的 MCP 服务器，提供草图、开发板、库和文件管理工具。由 FastMCP 提供支持。

快速开始

从 PyPI 安装并运行：

pip install mcp-arduino-server
mcp-arduino-server

概述

此服务器充当模型上下文协议 (MCP) 和 arduino-cli 之间的桥梁，允许 AI 代理或其他 MCP 客户端与 Arduino 开发工作流程进行交互。它提供了用于管理草图、编译代码、上传到开发板、管理库、发现硬件以及在受限环境中执行基本文件操作的工具。

功能

草图管理：创建、列出、读取和写入 Arduino 草图（.ino、.h 文件）。
- 写入主 .ino 文件会自动触发编译以进行验证。
- 自动打开：新创建的 .ino 文件会自动在您的默认编辑器中打开。
WireViz 电路图：
- YAML 编写帮助： 使用内置的 getWirevizInstructions 工具获取创建有效 WireViz YAML 的全面指南和示例。这些说明涵盖了如何定义连接器（组件）、电缆、连接和所需的元数据，以及清单和颜色代码参考。
- 图表生成： 使用 generate_diagram_from_yaml 工具从您的 YAML 生成电路图 PNG。您可以为输出指定草图目录，或让该工具创建一个带时间戳的文件夹。 PNG 以 base64 形式返回，并在您的图像查看器中自动打开。
- 典型工作流程：
  1. 调用 getWirevizInstructions 以查看 YAML 结构和示例。
  2. 编写您的 YAML 以描述您的 Arduino 电路。
  3. 使用您的 YAML 调用 generate_diagram_from_yaml 以获得可直接使用的 PNG 接线图。
- 错误处理： 服务器验证 YAML 结构，管理输出文件，并为无效的 YAML、缺少依赖项或 WireViz 故障提供清晰的错误消息。
- YAML 示例：（有关完整模板，请参见 getWirevizInstructions 的输出）
```
connectors:
  Arduino Uno:
    pinlabels: ["5V", "GND", "D2", "D3", "A4", "A5"]
    notes: 主控制板
  SSD1306 OLED Display:
    pinlabels: ["VCC", "GND", "SCL", "SDA"]
    notes: 显示模块
  # ... 更多组件 ...
cables:
  W_SSD1306_OLED:
    colors: [RD, BK, TQ, VT]
    category: bundle
connections:
  - # 连接示例
    - Arduino Uno: [3]
    - W_SSD1306_OLED: [1]
    - SSD1306 OLED Display: [1]
metadata:
  description: "带有 SSD1306 OLED 显示屏和按钮的 Arduino Uno 接线图"
  author: "用户"
  date: "2024-06-23"
```
代码验证：使用 verify_code 编译草图，无需上传。
上传：编译草图并上传到连接的开发板。
库管理：
- 搜索在线 Arduino 库管理器索引。
- 搜索本地平台库（如果安装了 thefuzz，则进行模糊搜索）。
- 从索引安装库。
- 列出已安装库的示例。
开发板管理：
- 发现连接的开发板及其详细信息（端口、名称、FQBN）。
- 列出与连接的开发板关联的平台库。
- 在在线开发板索引中搜索 FQBN。
文件操作：在用户的主目录或指定的草图目录中进行基本的、受限制的文件读取、写入、重命名和删除。
- 安全性：操作主要在 ~/Documents/Arduino_MCP_Sketches/ 和用户的主目录 (~) 中进行沙盒化，并对破坏性操作发出强烈警告。
强大的错误处理和日志记录：所有文件操作都具有广泛的日志记录、改进的错误消息和严格的路径验证。始终强调安全性。

先决条件

Python：3.8+（推荐 3.10+；mcp[cli] 等依赖项需要）
arduino-cli：必须安装并在系统 PATH 或常用位置（例如，/usr/local/bin、/opt/homebrew/bin）中可访问。服务器尝试自动检测。
WireViz：生成电路图需要。安装并确保它在您的 PATH 中。
MCP SDK：通过项目依赖项 (mcp[cli]) 安装。
模糊搜索（可选但推荐）：通过项目依赖项 (thefuzz[speedup]>=0.20.0) 安装。启用本地库搜索的模糊匹配。

安装

通过 pip 安装（推荐给大多数用户）：

pip install mcp-arduino-server

对于开发或高级用法，克隆存储库并安装依赖项：

git clone https://github.com/Volt23/mcp-arduino-server.git
cd mcp-arduino-server
pip install .

设置 Python 3.10+：确保您拥有 Python 3.10 或更高版本。建议使用 pyenv：

pyenv install 3.11.6 # 或最新的 3.10+
pyenv local 3.11.6

确保已安装并配置 arduino-cli：

按照官方 arduino-cli 安装指南。
您可能需要安装开发板核心（例如，arduino-cli core install arduino:avr）。

配置

服务器使用以下默认路径和设置。一些可以通过环境变量覆盖。

草图基本目录：~/Documents/Arduino_MCP_Sketches/
构建临时目录：~/Documents/Arduino_MCP_Sketches/_build_temp/
Arduino 数据目录：自动检测（~/.arduino15 或 ~/Library/Arduino15）
Arduino 用户目录：~/Documents/Arduino/
Arduino CLI 路径：通过 shutil.which 和常用路径自动检测。使用 ARDUINO_CLI_PATH 环境变量覆盖。
WireViz 路径：通过 shutil.which 自动检测（期望 wireviz 命令）。使用 WIREVIZ_PATH 环境变量覆盖。
默认 FQBN（用于写入时自动编译）：arduino:avr:uno。通过 write_file 中的 board_fqbn 参数覆盖。
日志级别：由 LOG_LEVEL 环境变量控制（例如，DEBUG、INFO、WARNING）。默认为 INFO。

用法

使用已安装的命令行脚本在其环境中运行服务器：

使用 uv：
```
uv run mcp-arduino-server
```

使用 pip（使用激活的 venv）：

# 确保您的虚拟环境已激活 (source .venv/bin/activate)
mcp-arduino-server

使用 WireViz 工具

YAML 编写帮助： 调用 getWirevizInstructions() 以接收全面的指南、清单和可直接使用的示例，用于编写有效的 Arduino 图 WireViz YAML。
图表生成： 调用 generate_diagram_from_yaml(yaml_content: str, sketch_name: str = "", output_filename_base: str = "circuit") 以从您的 YAML 生成 PNG 接线图。该工具验证您的 YAML，管理输出文件，返回确认和 PNG 图像（base64），并在您的图像查看器中自动打开它。
工作流程：
1. 使用 getWirevizInstructions 了解 YAML 格式。
2. 编写您的 YAML 以描述您的电路。
3. 使用 generate_diagram_from_yaml 创建和查看您的图表。

自动打开功能

当您创建一个新草图或生成一个图表时，相关文件将在您系统的默认应用程序（编辑器或图像查看器）中自动打开。

错误处理

所有文件操作和 CLI 交互都包含强大的错误消息和日志记录。检查日志以获取故障排除详细信息。

服务器将启动并侦听来自 MCP 客户端通过标准输入/输出 (stdio) 的连接。

与 MCP 客户端集成（例如，Claude Desktop）

在配置 MCP 客户端（例如 Claude Desktop）以启动此服务器时，您必须确保 JSON 配置中的 command 指向正确的执行文件。 如果您使用的是 pyenv 或自定义 Python 环境，请指定 mcp-arduino-server 二进制文件的完整路径，该文件已安装在该路径中。

例如，为了确保始终找到 WireViz，而不管 PATH 问题如何，您可以在 MCP 客户端配置中设置 WIREVIZ_PATH 环境变量（如果支持）：

{
  "mcpServers": {
    "arduino": {
      "command": "/Users/<您的用户名>/.pyenv/versions/<您的Python版本>/bin/mcp-arduino-server",
      "args": [],
      "env": {
        "WIREVIZ_PATH": "/Users/<您的用户名>/.pyenv/versions/<您的Python版本>/bin/wireviz"
      }
    }
  }
}

将 <您的用户名> 和 <您的Python版本> 替换为您的实际用户名和 Python 版本。这确保了 MCP 客户端启动正确的环境，并且始终找到 WireViz，即使您的 PATH 没有为 GUI 应用程序设置。

根据需要将 <您的用户名> 和 <您的Python版本> 替换为您的实际用户名和 Python 版本。这确保了 MCP 客户端启动正确的环境并找到所有依赖项。

可用工具（MCP 接口）

以下工具通过 MCP 接口公开：

create_new_sketch(sketch_name: str)：创建一个新的草图目录和 .ino 文件。
list_sketches()：列出草图目录中的有效草图。
read_file(filepath: str)：读取文件；如果读取主草图 .ino，则连接所有 .ino/.h 文件。
write_file(filepath: str, content: str, board_fqbn: str = DEFAULT_FQBN)：将内容写入文件；限制路径；自动编译主 .ino 文件。
rename_file(old_path: str, new_path: str)：在主目录中重命名/移动文件/目录。
remove_file(filepath: str)：删除主目录中的文件（不是目录）。 不可逆转。
list_boards()：列出连接的开发板、它们的 FQBN 和平台库。
board_search(board_name_query: str)：在在线索引中搜索开发板 FQBN。
verify_code(sketch_name: str, board_fqbn: str)：编译草图，无需上传。
upload_sketch(sketch_name: str, port: str, board_fqbn: str)：编译并上传草图。
lib_search(library_name: str, limit: int = 15)：搜索在线和本地平台库。
lib_install(library_name: str)：从索引安装/更新库。
list_library_examples(library_name: str)：列出已安装库的示例。
getWirevizInstructions()：返回详细的 YAML 编写说明和 WireViz 图的模板。
generate_diagram_from_yaml(yaml_content: str, sketch_name: str = "", output_filename_base: str = "circuit")：从 YAML 生成 PNG 接线图，返回图像和确认，自动打开 PNG。

有关每个工具的详细参数、返回值和潜在错误，请参阅服务器脚本的文档字符串 (src/mcp_arduino_server/server.py)。

调试技巧

检查服务器日志：服务器记录来自 arduino-cli 的详细错误。使用 export LOG_LEVEL=DEBUG 增加详细程度。
权限：确保运行服务器的用户具有对草图/构建目录的写入权限，以及对串行端口的读取/写入权限（例如，将用户添加到 Linux 上的 dialout 组）。
环境变量 PATH：验证 arduino-cli 和必要的工具链（例如，avr-gcc、bossac）是否在服务器进程可访问的 PATH 中。
核心/工具链：如果由于缺少核心而导致编译失败，请使用 arduino-cli core install <core_spec>（例如，arduino:avr）。
arduino-cli 命令：直接在您的终端中测试 arduino-cli 命令以隔离问题。

许可证

本项目根据 MIT 许可证获得许可。