tinysa-mcp

tinysa-mcp

通过串口操作 TinySA 的 MCP 服务

抱歉，我目前仍在试验中，无法保证它能正常运行。

概述

本项目是一个 MCP 服务，旨在通过串口操作 TinySA 设备。它利用 pyserial、httpx、numpy、Pillow 和 FastMCP 等 Python 库，提供基于工具的接口，用于连接设备、执行命令以及获取设备版本信息。

架构和线程模型

本项目同时使用基于 Tkinter 的 GUI 和 MCP 服务。由于 Tkinter 要求在主线程中运行，因此采用以下设计：

flowchart TD
    subgraph MainThread
        A[main()] --> B[tk.Tk() & TinySALogMonitor]
        B --> C[root.mainloop()]
    end
    subgraph MCPThread
        D[run_mcp_server(mcp_server)]
        D --> E[mcp_server.run()]
    end
    E -- log_callback --> F[log_monitor.log_queue]
    F -- root.afterで定期ポーリング --> B
    D -- サーバー終了時 --> G[root.after(0, root.destroy)]

• Tkinter GUI 在主线程中运行：
  主线程初始化 Tkinter 根窗口并启动主事件循环。所有 GUI 操作都在此线程中执行。

• MCP 服务在后台线程中运行：
  MCP 服务通过 Python 的 threading.Thread 在单独的线程中启动。这样，服务便能与 GUI 并发处理请求。

• 通过队列进行线程安全通信：
  MCP 服务（或其他后台线程）中的日志消息和其他数据通过 queue.Queue 发送到 GUI。GUI 使用 root.after 定期轮询此队列，以安全地更新显示内容。

• 优雅关闭：
  MCP 服务停止时，会通过 root.after(0, root.destroy) 安排关闭 GUI，确保所有 Tkinter 操作都在主线程中执行。

示例（主函数）：

def main():
    root = tk.Tk()
    log_monitor = TinySALogMonitor(root)
    mcp_server = create_mcp_server(log_monitor.add_log)
    mcp_thread = threading.Thread(target=run_mcp_server, args=(mcp_server,), daemon=True)
    mcp_thread.start()
    root.mainloop()

注意事项

• 请勿从后台线程访问 Tkinter 对象。
  始终使用提供的队列和 root.after 进行线程安全通信。
• 此设计可确保 MCP 服务和 GUI 并发运行，同时不违反 Tkinter 的线程要求。

功能

• 发送命令并获取设备响应。
• 获取固件和硬件版本信息。
• 提供 MCP 工具，以便与其他系统集成。
• 支持捕获设备屏幕图像，并可选择带时间戳保存到文件。

MCP 工具

可用的 MCP 工具如下：

• get_version：获取 TinySA 设备的版本信息。
• execute_command：向 TinySA 设备发送命令并获取响应。
• connect：连接到指定端口上的 TinySA 设备。
• disconnect：断开 TinySA 设备的连接。
• get_device_info：获取已连接设备的详细信息。
• capture_image：捕获 TinySA 屏幕图像，并可选择带时间戳保存到文件。

使用示例

使用 MCP 客户端调用 MCP 工具。例如，要获取设备版本：

mcp call get_version --args '{"port": "COM4"}'

故障排除

• 连接问题： 确保指定的串口正确，并且你的用户具有适当的权限。
• 命令失败： 检查 MCP 服务日志（如果有）中的错误消息。
• 图像捕获： 确认设备在捕获图像时返回了足够的数据（307200 字节）。
• 有关 MCP 集成的更多信息，请参阅 Model Context Protocol 文档。

材料

如需其他文档，请参阅 material 目录；建议将文件 "USB interface.txt" 添加为 AI 知识。

许可证

本项目采用 MIT License 许可。