MC3000 Charger

mc3000-mcp

为兼容 SKYRC MC3000 的充电器提供安全的本地 MCP 控制。

mc3000-mcp 将 AI Agent 连接到电池充电器，同时避免提供不受监督的硬件 API。BLE 控制在本地进行。默认采用充电模拟运行。实时写入和启动都需要针对每个插槽进行明确确认。紧急停止只需一次调用。

Agent  ──MCP stdio──  mc3000-mcp  ──BLE FFE0/FFE1──  SKYRC MC3000
                          │
                          ├─ profile validation and chemistry limits
                          ├─ dry-run profile rendering
                          ├─ confirmation tokens for live writes/starts
                          └─ bounded, redacted audit log

实现	Rust 二进制文件；无需 Python 运行时
MCP	stdio、27 个工具、资源和提示词
安全性	代码强制验证、默认模拟运行、明确确认
硬件	MC3000 读写；MC5000 只读
实机测试	MC3000 固件 1.23、硬件 2.20、NiMH 模式
注册表	crates.io、MCP Registry MCPB、AUR

硬件警告。 化学体系、电流、电压或插槽设置错误，或在无人监督的情况下充电，可能损坏电芯或引发火灾。MCP 服务才是安全边界，而不是 LLM。请确保充电器始终在视线范围内。请参阅 SECURITY.md。

安装

# crates.io
cargo install mc3000-mcp --locked

# Arch Linux
paru -S mc3000-mcp

# released tag, if you prefer installing from source
cargo install --git https://github.com/nietonchique/mc3000-mcp.git --tag v0.2.1 --locked

每次发布都会附带 Linux x86_64 MCPB 包，供兼容 MCPB 的客户端使用。

Linux BLE 需要 BlueZ/D-Bus：

bluetoothctl show
# If the adapter is off:
sudo rfkill unblock bluetooth && bluetoothctl power on

连接 MCP 客户端

{
  "mcpServers": {
    "mc3000": {
      "command": "mc3000-mcp",
      "args": []
    }
  }
}

客户端专用示例见 examples/。

无需硬件即可试用：

{
  "mcpServers": {
    "mc3000": {
      "command": "mc3000-mcp",
      "args": ["--backend", "fake"]
    }
  }
}

Agent 技能

charger-agent 使用可移植的 Agent Skills 布局：一个包含 SKILL.md 清单的文件夹。无需特定供应商的安装程序。

为 Codex 安装：

mkdir -p ~/.codex/skills
curl -fsSL https://github.com/nietonchique/mc3000-mcp/releases/download/v0.2.1/mc3000-mcp-skill-v0.2.1.tar.gz \
  | tar -xz -C ~/.codex/skills

对于 OMP，将 ~/.omp/agent/skills 作为目标目录。对于兼容 Claude 的客户端，使用 ~/.claude/skills。Hermes 也可以安装原始文件，但它只是一个兼容客户端，并非分发格式。

该文件夹包含充电器工作流、启动前检查清单和示例配置文件。它们仅供参考；Rust MCP 服务仍是强制执行安全措施的边界。

CLI

默认命令会启动 MCP stdio。也可以直接运行只读诊断：

mc3000-mcp --version
mc3000-mcp scan --timeout 8
mc3000-mcp status --address AA:BB:CC:DD:EE:FF
mc3000-mcp --backend fake scan

CLI 可以扫描并读取插槽。它无法写入配置文件、更改设置或启动充电。

安全工作流

1. 读取插槽状态。
2. 验证电池配置文件。
3. 将其渲染为模拟运行。
4. 使用 confirmation_token=APPLY_PROFILE_SLOT_<slot> 应用配置。
5. 使用单独的 confirmation_token=START_SLOT_<slot> 启动。
6. 监控电压、电流、温度和状态。
7. 如果发现任何异常，立即使用 charger.stop_slot / charger.stop_all。

物理插槽 4 / API 插槽 3 的模拟运行示例：

{
  "name": "charger.apply_profile",
  "arguments": {
    "slot": 3,
    "profile_id": "nimh-aa-conservative-charge"
  }
}

启动需要第二次明确确认：

{
  "name": "charger.start",
  "arguments": {
    "slot": 3,
    "confirmation_token": "START_SLOT_3"
  }
}

紧急停止有意不使用令牌：

{"name": "charger.stop_all", "arguments": {}}

工具

生产环境接口均使用 charger.* 命名空间：

工具	用途
scan_devices	只读 BLE 扫描。
connect / disconnect	管理充电器连接。
get_status、read_slots	插槽化学体系、模式、电压/电流、温度和状态。
get_voltage_curve、export_voltage_curve	以 JSON/CSV 格式导出充电器存储的电压序列。
list_profiles、validate_profile	内置配置文件和强制安全检查。
apply_profile	默认模拟运行；实时写入需要该插槽的令牌。
start	启动已准备好的插槽；需要单独的令牌。
stop_slot、stop_all	立即紧急停止。
export_session_log	有限长度且已脱敏的审计日志。

此外还保留了十四个旧版 mc3000_* 工具，用于协议调试工作。非紧急写入同样遵循确认策略。原始写入无法隐式启动插槽，并且始终会阻止执行恢复出厂设置/校准操作码。

安全模型

• API 插槽从 0..3 开始编号；物理插槽从 1..4 开始编号。
• apply_profile 默认为 dry_run=true。
• 实时写入配置文件必须准确提供 APPLY_PROFILE_SLOT_<slot>。
• 启动必须准确提供 START_SLOT_<slot>。
• 安全检查会在任何后端调用前运行；不支持的化学体系会被拒绝。
• NiMH/Eneloop/NiCd、LiIon 和 LiFe 均设有强制限制。
• 未知充电器型号和 MC5000 连接均为只读。
• 会话日志会对地址和确认令牌进行脱敏，并限制内存占用。

完整模型：docs/safety-model.md。 配置文件架构及随附示例：docs/profile-schema.md。

兼容性

已确认可实时使用：SKYRC MC3000 固件 1.23，硬件 2.20。

协议详情根据官方 Android 应用及硬件测试记录，见 docs/ble-protocol-notes.md 和 docs/reverse-notes.md。在真实硬件上验证写入功能之前，MC5000 支持将保持只读。

充电器固件的行为可能有所不同。配置文件写入确认并不能证明充电器已应用该配置——请启动插槽并验证模式／电流／状态。

开发

cargo fmt --all -- --check
cargo clippy --all-targets --all-features --locked -- -D warnings
cargo test --all-features --locked
cargo audit && cargo deny check

虚假后端可确保常规测试和 CI 不会接触硬件。完整工作流及硬件安全规则请参阅 CONTRIBUTING.md。

文档

• 安全与漏洞披露：SECURITY.md
• 安全模型：docs/safety-model.md
• 支持的设备：docs/supported-devices.md
• 示例：docs/examples.md
• 发布／发布流程清单：docs/publishing.md
• Agent 技能：skill/SKILL.md

许可证

Apache-2.0。请参阅 LICENSE。