operandi

Name: operandi
Author: operandi.cc

本地服务

github.com/ArchieAngelBeWithUs-prog其他014 周前更新

代码仓库

关于 operandi

OPERANDI 是面向 Agent 和机器人规划器的 MCP 服务，为真实家电提供有依据的操作说明。它可识别型号，并返回型号专属流程、验证信号、恢复步骤和安全范围。

主要功能

01通过铭牌或型号识别家电
02获取型号专属操作包
03提供控制映射及依据
04提供逐步验证信号
05包含恢复状态和安全范围

适用场景

01根据铭牌识别家电
02为机器人提供有依据的操作流程
03操作时检查步骤和恢复选项

MCP 相关

向 MCP 客户端提供家电识别、目录浏览、能力搜索和操作包工具。服务器使用 MCP stdio 传输，并与 OPERANDI REST 服务通信。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "cc-operandi-operandi": {
      "command": "uvx",
      "args": [
        "operandi-mcp"
      ],
      "env": {
        "OPERANDI_API_URL": "<OPERANDI_API_URL>",
        "OPERANDI_API_KEY": "<OPERANDI_API_KEY>"
      }
    }
  }
}

启动命令uvx operandi-mcp

需要配置的环境变量

OPERANDI_API_URLBase URL of the OPERANDI API (default https://api.operandi.cc; use your hosted URL in prod).

OPERANDI_API_KEY密钥Optional: your OPERANDI key. Leave unset for a zero-config instant trial (the server mints + caches its own key, 2 packages included).

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

pypioperandi-mcp1.0.3stdio

工具

收录的工具列表 · 更新于 2 周前

参数	类型	必填	说明
brand	string	否	可选的品牌提示（如果已知）。
limit	integer	否	匹配项上限（1–20，默认值为 5）。
query	string	是	观察到的铭牌／型号文本（例如 'Samsung ME20H705MSS'）。
category	string	否	可选的类别提示，例如 'microwave_oven'。
panel_labels	array	否	可选的控制面板标签 OCR 文本（当铭牌被遮挡时有助于识别）。

详细介绍

OPERANDI MCP Server — 通过任意 Agent 操作真实家电

mcp-name: cc.operandi/operandi

operandi_mcp_server.py 通过 Model Context Protocol 暴露 OPERANDI，让任何支持 MCP 的 Agent 宿主（Claude Desktop、Claude Code 或你自己的 Agent 运行时）都能识别家电，并以原生工具的形式获取基于真实依据、经过安全检查且可由机器人执行的操作包。

这是面向 Agent 构建的界面：客户是机器人的规划器／LLM Agent，而不是阅读 PDF 的人类。

工具

工具	功能
`identify_appliance`	将观察到的铭牌文字／面板标签／型号解析为目录对象（请首先调用）。
`get_operation_package`	机器人可执行的操作包：精确到型号的流程、控制映射与依据、逐步验证信号、恢复状态机、安全边界。
`list_appliances`	浏览可操作的家电（可按类别筛选）。
`find_by_capability`	按功能查找家电（`heat`／`wash`／`brew`／`defrost` …）。

Agent 为什么需要它

通用大模型在缺少依据时，经常会对普通家电给出自信却错误的实体操作指示（OPERANDI Stage A：24% 的无依据指示会导致操作失败，包括虚构的按钮和程序）。借助这些工具返回的操作包作为依据，这一比例降至 0 次幻觉，96% 完全准确。这些工具将“猜按钮”变成“读取制造商的真实信息”。参见 ../docs/BUSINESS_MODEL.md。

设置 — 无需配置

pip install operandi-mcp

就这么简单。获取首批操作包无需密钥：首次使用时，服务会自行创建一个即时试用密钥（POST /v1/trial — 无需注册，包含 2 个操作包，并缓存于 ~/.operandi/mcp_key）。试用额度用完后，工具响应会准确告知 Agent 如何免费注册（每月 10 个操作包）或升级到 Pro。

已有密钥？设置后会优先使用该密钥，而非试用密钥：

export OPERANDI_API_KEY=ok_live_...

Claude Desktop / Claude Code 配置

{
  "mcpServers": {
    "operandi": { "command": "operandi-mcp" }
  }
}

（可选：拥有账户密钥后，可添加 "env": {"OPERANDI_API_KEY": "ok_live_..."}。）

然后向 Agent 提问：“识别 Samsung ME20H705MSS，并告诉我安全解冻 0.5 kg 肉末的操作流程。”——它会调用 identify_appliance，然后调用 get_operation_package，并根据有依据的数据作答。

说明

该服务是一个精简的、通过 API 密钥验证身份的 REST 客户端——只需更改 OPERANDI_API_URL，同一二进制文件即可连接本地开发环境或托管服务。
身份验证使用 Authorization: Bearer <key>；密钥缺失或无效时会显示工具错误，不会导致崩溃。
传输协议为以换行符分隔的 JSON-RPC 2.0（MCP stdio 传输）。离线协议测试： pytest tests/test_mcp_server.py。