cfrs2005 mcp gs robot

An open-source ops agent for Gausium cleaning robots — MCP server, REST API, CLI and mobile web, on OpenAPI V3.

_{package mcp-gs-robot · pip install mcp-gs-robot}

5-minute start · Let your AI agent set it up · Safety · Cognition & memory · Tools · HTTP API & H5 · Configuration · Troubleshooting · 中文文档

⚠️ Disclaimer — This is an unofficial, open-source project for personal research and learning. Not affiliated with, endorsed by, or supported by Gausium (高仙). Use at your own risk — robot commands move physical machines, so test on simulators or idle robots first. Built solely from the public Gausium OpenAPI V3 documentation.

_{The built-in H5 app, left to right: Home · Result cards · Execution pipeline · Robots · Current location. Running against a mock upstream with demo data.}

mcp-gs-robot wraps the Gausium OpenAPI V3 (robot status, maps, combined tasks, schedules, commands, reports) in a typed Python client, and exposes it through four entry points that share one tool registry:

• 42 tools — all 36 V3 business endpoints, the legacy robot list, local lookups (describe_work_state, lookup_error_code), local memory (remember) and workflow helpers (run_cleaning_task, wait_for_command)
• Typed & tested — pydantic v2 models, envelope unwrapping, upstream errors (6-digit platform codes, 10-digit robot task codes) surfaced as GausiumAPIError; offline test suite with a mock HTTP transport
• Safety first — every tool that moves a robot or writes data is flagged dangerous and needs explicit approval in the Agent, CLI and H5
• Gets smarter with use — sessions, tool calls and error threads are kept in a local SQLite file; verified lessons go into a private memory file that every new session loads
• Provider-agnostic Agent — Anthropic (default, claude-opus-5) or any OpenAI-compatible endpoint (DeepSeek, vLLM, Ollama…); it answers in the language you write in
• Built strictly on the official docs — docs/apis.md maps each endpoint to its official page; the full contract is docs/ARCHITECTURE_V3.md

Prerequisites: Python 3.12+, uv, and Gausium open-platform credentials (an application plus an AccessKey from the Gausium Developer Center). Node 18+ is only needed if you want to rebuild the H5 app — a production build is already committed.

1 · Install

git clone https://github.com/cfrs2005/mcp-gs-robot.git
cd mcp-gs-robot
uv sync --extra dev

(Or pip install mcp-gs-robot if you only need the commands; the wheel ships the H5 build and the skill.)

2 · Configure — cp .env.example .env, then fill in:

.env is read from the current working directory by every entry point, is git-ignored, and must never be committed. Real environment variables take precedence over .env.

3 · Run an entry point (from the repository root)

Check that the server is up: curl -s http://127.0.0.1:8000/api/v1/health → {"status":"ok", …, "auth_required":true}. auth_required: true means the H5 needs the key before anything else works.

uv run saodi --show-context prints Saodi's full system prompt without any key — a quick way to confirm the install.

Paste this into Claude Code, Codex or Cursor (agent mode). It installs, configures, tests and smoke-tests the project with read-only calls only. The same prompt, with a Chinese version, is in docs/AGENT_SETUP_PROMPT.md.

Set up mcp-gs-robot (an unofficial MCP / REST / agent wrapper for the Gausium OpenAPI V3) on this
machine. Work step by step, show me each command's result, and stop at the first failure.

Hard rules
- Robots are physical machines. Call read-only tools only. Never call a tool marked dangerous
  (anything that creates, updates or deletes tasks or schedules, starts / pauses / resumes / stops /
  skips tasks, navigates, runs a cleaning workflow, or writes memory with `remember`).
- Never print, echo, log or commit credentials. Write them only into .env with your file-edit tool
  (not via shell echo), never paste them back to me, and confirm .env is git-ignored.

Steps
1. Prerequisites: `python3 --version` (3.12+) and `uv --version`. `node --version` (18+) only
   matters for step 5.
2. `git clone https://github.com/cfrs2005/mcp-gs-robot.git && cd mcp-gs-robot && uv sync --extra dev`
3. `cp .env.example .env`. Ask me for GS_CLIENT_ID, GS_CLIENT_SECRET and GS_OPEN_ACCESS_KEY (the
   AccessKeySecret, not the AccessKeyID), and whether to use production
   (https://openapi.gs-robot.com/) or test (https://openapi.dev.gs-robot.com/) for GS_BASE_URL.
   Ask which LLM provider I use: Anthropic (SAODI_PROVIDER=anthropic + ANTHROPIC_API_KEY) or an
   OpenAI-compatible endpoint (SAODI_PROVIDER=openai + OPENAI_BASE_URL + OPENAI_API_KEY +
   SAODI_MODEL). Generate GS_SERVER_API_KEY yourself with
   `python3 -c "import re,secrets,pathlib;p=pathlib.Path('.env');p.write_text(re.sub(r'(?m)^GS_SERVER_API_KEY=.*$','GS_SERVER_API_KEY='+secrets.token_urlsafe(32),p.read_text()))"` (it rewrites the line in .env in place and never prints the key; I will read it from .env myself).
   Then run `git check-ignore .env` (it must print .env) and `git status --short` (.env must not
   appear).
4. `uv run pytest -q` and `uv run ruff check src tests`; both must pass.
5. If Node 18+ is available: `cd h5 && npm ci && npm run build && cd ..`. Otherwise skip; a
   prebuilt H5 is already in src/gs_openapi/server/static/.
6. Start the server in the background with its output in a log file:
   `uv run gs-robot-server > server.log 2>&1 &`
7. `curl -s http://127.0.0.1:8000/api/v1/health` must return "status":"ok" and
   "auth_required":true.
8. Tell me to open http://localhost:8000/, go to Settings, paste the GS_SERVER_API_KEY value from
   .env and press Save (it should report the connection as OK). Do not show me the key yourself.
9. Read-only smoke test. Load the key without printing it:
   `KEY=$(grep '^GS_SERVER_API_KEY=' .env | cut -d= -f2-)`
   - `curl -s -X POST -H "X-API-Key: $KEY" -H 'Content-Type: application/json'
     -d '{"page":1,"page_size":5}' http://127.0.0.1:8000/api/v1/tools/list_robots`
   - pick one robot from that list with "online": true and call get_robot_status the same way
     with body {"robot_sn_list":["<that SN>"]}.
   Error meanings: 401 = wrong or missing X-API-Key; 110003 = these credentials are not bound to
   that robot (not "no data"); 230003 = robot offline; 100026 = rate limited, slow down.
10. Report: tool versions, pytest / ruff results, the health response, how many robots are
    online / offline, and any error as `<code> <msg>`. Leave out secrets and trace IDs.

claude mcp add gs-robot -- uv --directory /path/to/mcp-gs-robot run mcp-gs-robot

{
  "mcpServers": {
    "gs-robot": {
      "command": "mcp-gs-robot",
      "env": { "GS_CLIENT_ID": "…", "GS_CLIENT_SECRET": "…", "GS_OPEN_ACCESS_KEY": "…" }
    }
  }
}

uv run gs-robot-server              # http://0.0.0.0:8000 (GS_SERVER_HOST / GS_SERVER_PORT)

uv run saodi                                   # provider and keys from .env
uv run saodi --robot <robot-sn>                # scope the session to one robot
uv run saodi --show-context                    # print the system prompt and exit (no key needed)

you> Is the lobby robot free? Enough battery for a full dust-push?
⚙ get_robot_status(robot_sn_list=["<robot-sn>"])
Online, 82% battery, IDLE on map "Lobby" — good to go.
you> Start the lobby dust-push task
⚙ list_task_definitions(...)
Approve start_task robot_sn=<robot-sn> fusion_task_id=…? [y/N] y
⚙ start_task(...)  ⚙ wait_for_command(...)
Command delivered (cmdStatus=6); it is not finished yet — I'll check workState again in ~30 s.

uv run saodi memory                            # path and content of the local memory file
uv run saodi memory add "<lesson>" [--scope S] # add one lesson by hand
uv run saodi memory edit                       # open it in $VISUAL / $EDITOR
uv run saodi errors [--status open] [--json]   # error threads from the tool-call log
uv run saodi errors show <id>                  # one thread with its recent calls
uv run saodi errors promote <id>               # turn a thread into a memory lesson

cp -r skills/gs-robot ~/.claude/skills/gs-robot     # Claude Code (user scope)
cp -r skills/gs-robot ~/.codex/skills/gs-robot      # Codex CLI

Tools that move a robot or write data are registered with dangerous=True. Saodi never runs them on its own: it emits confirm_required and waits — [y/N] in the terminal, buttons in the H5, POST …/confirm over REST. A rejected call never reaches the robot (or the memory file).

Keep in mind:

• Delivered is not finished. cmdStatus=6 means the robot received the command; follow up with get_robot_status or task reports.
• REST executes directly. POST /api/v1/tools/{name} treats the caller as already having confirmed — gate it in your own client. SAODI_AUTO_APPROVE=1 disables the Agent gate (not recommended).

For the common "clean these areas" case, run_cleaning_task bundles the whole procedure into one confirmed call:

Every new session gets one system prompt, assembled in this order and fixed for the session (saodi --show-context prints it):

The official error-code table (skills/gs-robot/references/error-codes.md, ~23 KB) is not loaded into every prompt: Saodi calls the read-only lookup_error_code tool when it meets a code it does not know, and is told not to guess. The whole prompt is capped by SAODI_CONTEXT_MAX_CHARS (default 60000); when it overflows, the oldest local memory entries are dropped first and a WARNING says how many.

How it gets smarter

1. remember in chat. When Saodi learns something verified and reusable — what an error code means in practice, a robot's lasting quirk, your preferences — it proposes remember(lesson). That writes a file, so it asks for confirmation like any dangerous tool. On approval it appends - [YYYY-MM-DD] lesson to memory.md; duplicates are skipped and anything that looks like a credential (token / secret / Bearer / long random strings) is refused. It does not remember one-off data (today's battery, a single snapshot) or guesses. The next session loads the new line.
2. From errors to lessons. Every tool call is logged locally; failures are folded into error threads. saodi errors lists them, PATCH /api/v1/errors/threads/{id} (try it in Swagger at /docs) lets you set the status, category and a note, and saodi errors promote <id> writes the note (or, if empty, the category and sample message) into memory.md and marks the thread as promoted.
3. By hand. saodi memory add "…" or saodi memory edit.
4. Back to everyone. If a lesson is general, propose it for experience.md in a pull request. Writing rule: general behaviour and how to handle it only — no robot SNs, trace IDs, request IDs, accounts, credentials, customer or site names.

All 42 tools are defined once in gs_openapi/tools/ and exposed identically to MCP, the Agent and REST (POST /api/v1/tools/{name}). Inputs are snake_case; the registry maps them to V3 camelCase. ⚠️ = dangerous.

Regenerate the list from the registry:

uv run python -c "from gs_openapi.tools.registry import REGISTRY; [print(t.category, t.name, '⚠️' if t.dangerous else '') for t in REGISTRY.values()]"

Base prefix /api/v1. GET /health is public; everything else requires X-API-Key when GS_SERVER_API_KEY is set. Errors share one envelope, {"error": {"code", "message", "trace_id"}}; upstream V3 errors become HTTP 502 carrying the business code.

SSE events from /messages: text_delta · tool_call · tool_result · confirm_required · done · error. Sessions are stored in SQLite, so a conversation survives a server restart.

KEY=$(grep '^GS_SERVER_API_KEY=' .env | cut -d= -f2-)
SID=$(curl -s -XPOST -H "X-API-Key: $KEY" localhost:8000/api/v1/agent/sessions | jq -r .session_id)
curl -N -XPOST -H "X-API-Key: $KEY" -H 'Content-Type: application/json' \
  -d '{"content":"List my robots and their battery"}' \
  localhost:8000/api/v1/agent/sessions/$SID/messages

H5 (h5/, Vue 3 + Vite + Vant): Chat (a home screen with greeting, suggested questions and a fleet overview; streaming Markdown, HTML preview and mermaid diagrams; a tool-call timeline with result cards for robots, report KPIs, daily trends and maps; an execution pipeline card for dangerous tools — confirm → sent → delivered, nothing runs until approved; and a history drawer), Robots (fleet list with search and filters, online / offline / unreachable states, battery and work state), Detail (current location — the robot, its heading and map points on the map — maps & canvas, task definitions, quick actions, reports; offline robots get a banner instead of errors) and Settings (API base, API key, language). When the server needs a key and none is saved, the H5 sends you to Settings. The production build is committed to src/gs_openapi/server/static/, so pip install ships it.

• H5: English and 中文, switchable under Settings → Language (the first visit follows the browser language).
• Saodi: replies in the language you write in; field names such as workState or cmdStatus stay in English.
• Docs: English is the primary language; README_CN.md mirrors this file in Chinese. Tool descriptions are bilingual.

Deprecated names, read for one more release when the new name is unset (each prints one WARNING with the name only):

src/gs_openapi/
├── auth/token_manager.py      OAuth token (ms-epoch expiry, locked refresh)
├── core/                      HTTP client, V3 endpoint registry, errors
├── v3/                        GausiumV3 facade · pydantic models · reference tables
├── tools/                     Tool registry (single source for MCP / Agent / REST) + knowledge tools
├── mcp/                       FastMCP server (v3_server.py) + legacy_tools.py
├── agent/                     Saodi core, soul.md, prompt builder, providers, sessions, CLI
├── store/                     SQLite sessions / tool-call log / error threads, local memory.md
├── server/                    FastAPI app, routes, SSE, static H5 hosting
└── main.py                    `mcp-gs-robot` stdio entry
h5/                            Vue 3 mobile web app (builds into server/static)
skills/gs-robot/               Agent Skill + references (also Saodi's Knowledge / Memory)
docs/ARCHITECTURE_V3.md        The contract every module follows
tests/                         Offline tests (httpx.MockTransport, no network)

uv sync --extra dev
uv run pytest -q
uv run ruff check src tests
cd h5 && npm ci && npm run build    # rebuild the H5 into src/gs_openapi/server/static
uv build                            # wheel includes the H5 assets and the skill

To add a V3 tool, define the input model and handler in src/gs_openapi/tools/v3_tools.py with @tool(...); MCP, REST and the Agent pick it up automatically. Add a test and a row to the tool tables. Conventions are in CLAUDE.md; curl walkthroughs and MCP Inspector usage are in the Testing Guide.

Fork, create a feature branch, uv sync --extra dev, make your change with tests, run uv run pytest -q && uv run ruff check src tests, update the tool tables if you touched the registry, and open a pull request. Experience for experience.md is welcome — general behaviour only, with no SNs, trace IDs, accounts, credentials or customer / site names.

MIT — see LICENSE.

This project is an unofficial, open-source effort for personal research and learning, built only from Gausium's public OpenAPI V3 documentation. It is not affiliated with, endorsed by, or supported by Gausium. No warranty of any kind; you are responsible for any robot you command. Always validate on simulators or idle machines first, keep credentials out of version control, and remember that a delivered command (cmdStatus=6) is not a completed task.