Serial Shell MCP

串行mcp

一种模型上下文协议（MCP）服务器，通过stdin/stdout上的JSON-RPC将Windows串行COM端口暴露给Codex或任何兼容MCP的客户端。

特性

• 枚举可用的COM端口。
• 使用可配置的波特率、数据位、停止位、奇偶校验和超时打开和管理多个串行会话（每个端口一个）。
• 将UTF-8、十六进制或base64编码的有效载荷发送到端口。
• 从具有可配置字节限制和超时的开放端口读取。
• 断开会话并检查活动连接以进行诊断。
• 可选的端口允许列表和通过环境变量进行的运行时配置。
• 结构化日志记录 tracing.

建筑

服务器以Windows 11为目标，并生成单个可执行二进制文件。

# Build release binary (on Windows)
cargo build --release
# Expected output: target/release/serial-shell-mcp.exe

要从安装了MSVC工具链的另一台主机进行Windows交叉编译，请执行以下操作：

rustup target add x86_64-pc-windows-msvc
cargo build --release --target x86_64-pc-windows-msvc
# Output: target/x86_64-pc-windows-msvc/release/serial-shell-mcp.exe

跑步

服务器使用JSON-RPC 2.0通过stdin/stdout进行通信。

./target/release/serial-shell-mcp.exe

加工方法遵循MCP惯例：

• initialize：返回服务器信息和广告工具。
• list_tools / tools/list：返回工具架构。
• call_tool / tools/call：使用以下命令执行工具 name 和 arguments.

可用工具

• serial_list_ports –列出带有可选描述的COM端口。
• serial_connect –打开端口并创建会话（返回 session_id).
• serial_disconnect –结束会话 session_id.
• serial_read –阅读至 max_bytes 带可选的字节 timeout_ms 以（权力）否决
• serial_send –发送数据，可选 encoding (utf-8, hex, base64).
• serial_list_sessions –调试助手列出活动会话。

- 注意：底层串行库支持一个或两个停止位；接受1.5个停止位的请求但强制为两个停止位并记录警告。

有效载荷示例

列出工具：

{"jsonrpc":"2.0","id":1,"method":"list_tools"}

连接到 COM3:

{
  "jsonrpc":"2.0",
  "id":2,
  "method":"call_tool",
  "params":{
    "name":"serial_connect",
    "arguments":{"port":"COM3","baud":115200}
  }
}

发送文本：

{
  "jsonrpc":"2.0",
  "id":3,
  "method":"call_tool",
  "params":{
    "name":"serial_send",
    "arguments":{"session_id":"","data":"help"}
  }
}

阅读：

{
  "jsonrpc":"2.0",
  "id":4,
  "method":"call_tool",
  "params":{
    "name":"serial_read",
    "arguments":{"session_id":"","max_bytes":512,"timeout_ms":200}
  }
}

断开连接：

{"jsonrpc":"2.0","id":5,"method":"call_tool","params":{"name":"serial_disconnect","arguments":{"session_id":""}}}

配置

环境变量覆盖默认值：

• SERIAL_MCP_DEFAULT_BAUD （默认值 115200)
• SERIAL_MCP_DEFAULT_TIMEOUT_MS （默认值 100)
• SERIAL_MCP_LOG_LEVEL (error, warn, info, debug, trace；默认 info)
• SERIAL_MCP_ALLOWED_PORTS （逗号分隔的允许列表，如 COM3,COM4)

Codex配置示例

增添 config.toml:

[[mcp.servers]]
id = "serial-mcp"
command = "C:\\Tools\\serial-shell-mcp.exe"
args = []
auto_start = true

安全注意事项

• 可选择通过以下方式限制对特定端口的访问 SERIAL_MCP_ALLOWED_PORTS.
• 日志包括用于审计的工具调用和端口生命周期事件。
• 二进制/换行扩展可以稍后添加，而不会破坏当前的API。