mcpField
O
operandi

operandi

Local
github.com/ArchieAngelBeWithUs-progOther0Updated 14w ago
Repository

About operandi

OPERANDI is an MCP server for agents and robot planners that need grounded operating instructions for real appliances. It identifies models and returns model-specific procedures with verification signals, recovery steps, and safety limits.

Key features

  1. 01Identify appliances from labels or model names
  2. 02Retrieve model-specific operation packages
  3. 03Include control maps and grounding
  4. 04Provide per-step verification signals
  5. 05Include recovery states and safety limits

Use cases

  1. 01Find an appliance from its nameplate
  2. 02Give a robot a grounded operating procedure
  3. 03Check steps and recovery options during operation

MCP support

Exposes appliance identification, catalog, capability search, and operation-package tools to MCP clients. It uses the MCP stdio transport and communicates with an OPERANDI REST service.

Configuration

Local server config is the same for every client. Copy it into your client’s MCP config file.

mcp.json · Universal config
{
  "mcpServers": {
    "cc-operandi-operandi": {
      "command": "uvx",
      "args": [
        "operandi-mcp"
      ],
      "env": {
        "OPERANDI_API_URL": "<OPERANDI_API_URL>",
        "OPERANDI_API_KEY": "<OPERANDI_API_KEY>"
      }
    }
  }
}
Run commanduvx operandi-mcp
Environment variables to set
OPERANDI_API_URLBase URL of the OPERANDI API (default https://api.operandi.cc; use your hosted URL in prod).
OPERANDI_API_KEYSecretOptional: your OPERANDI key. Leave unset for a zero-config instant trial (the server mints + caches its own key, 2 packages included).

Local servers need a runtime on your machine (e.g. Node.js 18+). Config file locations differ by client; see your client’s docs.

Packages
pypioperandi-mcp1.0.3

Tools

4

Saved tool list · updated 2w ago

ParameterTypeRequiredDescription
brandstringNoOptional brand hint if known.
limitintegerNoMax matches (1-20, default 5).
querystringYesObserved nameplate / model text (e.g. 'Samsung ME20H705MSS').
categorystringNoOptional category hint, e.g. 'microwave_oven'.
panel_labelsarrayNoOptional control labels OCR'd off the panel (helps when the nameplate is hidden).

Details

From the project README

OPERANDI MCP Server — operate real appliances from any agent

mcp-name: cc.operandi/operandi

operandi_mcp_server.py exposes OPERANDI over the Model Context Protocol so any MCP-capable agent host (Claude Desktop, Claude Code, or your own agent runtime) can identify an appliance and pull its grounded, safety-checked, robot-executable operation package as native tools.

This is the "build for agents" surface: the customer is a robot's planner / an LLM agent, not a human reading PDFs.

Tools

ToolWhat it does
identify_applianceResolve observed nameplate text / panel labels / model → a catalog object (call first).
get_operation_packageThe robot-executable package: model-exact procedures, control map + grounding, per-step verification signals, recovery state machine, safety envelope.
list_appliancesBrowse operable appliances (optionally by category).
find_by_capabilityFind appliances by function (heat / wash / brew / defrost …).

Why an agent wants this

A general model, cold, gives confidently-wrong physical instructions on ordinary appliances a large fraction of the time (OPERANDI Stage A: 24% of cold instructions were would-fail, including invented buttons and cycles). Grounded in the package these tools return, that fell to 0 hallucinations, 96% exact. The tools turn "guess the buttons" into "read the manufacturer's ground truth". See ../docs/BUSINESS_MODEL.md.

Setup — zero config

pip install operandi-mcp

That's it. No key needed for your first packages: on first use the server mints an instant trial key itself (POST /v1/trial — no signup, 2 operation packages included, cached at ~/.operandi/mcp_key). When the trial is spent, tool responses tell the agent exactly how to sign up free (10 packages/month) or go Pro.

Have a key already? Set it and it wins over the trial:

export OPERANDI_API_KEY=ok_live_...
Claude Desktop / Claude Code config
{
  "mcpServers": {
    "operandi": { "command": "operandi-mcp" }
  }
}

(Optionally add "env": {"OPERANDI_API_KEY": "ok_live_..."} once you have an account key.)

Then ask the agent: "Identify the Samsung ME20H705MSS and give me the safe procedure to defrost 0.5 kg of mince." — it will call identify_appliance then get_operation_package and answer from grounded data.

Notes

  • The server is a thin, API-key-authenticated REST client — the same binary works against local dev or the hosted service by changing OPERANDI_API_URL.
  • Auth is Authorization: Bearer <key>; a missing/invalid key surfaces as a tool error, not a crash.
  • Transport is newline-delimited JSON-RPC 2.0 (the MCP stdio transport). Offline protocol tests: pytest tests/test_mcp_server.py.

Comments

Markdown supported

New to MCP?

From what the protocol is to installing your first server, these answers cover most first questions.

An open protocol that defines how AI applications connect to external tools and data in a uniform way. Clients talk to the model; MCP servers provide tools, resources and prompt templates. They exchange standard messages, so one server can be reused by many clients.