robomcp
Provides tools for searching and reading ROS 2 documentation: a keyword (BM25) search over ~2,730 documentation sections that returns short snippets plus section ids, and a paged read tool for pulling the full text of a specific section, letting an agent find answers and rephrase queries when nothing relevant surfaces.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@robomcp check robot 2's battery, then move it to the packing station"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A Model Context Protocol server that gives an LLM agent tools for a simulated warehouse robot fleet and for searching the ROS 2 documentation, with a permission policy between the model and anything that moves. The goal is to measure how reliably an agent completes fleet tasks through these tools: when it needs approval, when a tool fails, and when text it reads tries to hijack it.
Status: work in progress. The server, the 16 tools, the permission policy, the simulated fleet and the documentation search are done and tested. The agent itself is next (Claude and a local model behind the same loop, a task suite with checkable end states, injected tool failures), followed by a prompt-injection test set and the evaluation over seeded runs.
Design
flowchart LR
A[agent: LLM + tool loop] -- MCP, stdio --> S[robomcp server]
S --> E[executor]
E --> V[JSON Schema check] --> P{policy}
P -- allow --> H[tool handler]
P -- ask --> O[operator approval] --> H
P -- deny --> X[error with code + reason]
H --> W[simulated fleet: battery, faults, keep-out areas]
H --> D[BM25 over ROS 2 doc sections]
E -.-> L[audit log, every call]Every tool belongs to one tier, and the policy file maps tiers to allow, ask or deny:
Tier | Tools | Shipped policy |
read | list_robots, get_robot_state, list_locations, get_params, read_diagnostics, plan_route, search_docs, read_doc_section | allow |
stop | emergency_stop | allow |
config | set_param, restart_node | ask, and only max_speed / goal_tolerance and three named nodes |
motion | navigate_to, dock, pick_item, drop_item | ask |
release | clear_emergency_stop | deny |
The fleet is a small deterministic simulator, not ROS: three robots in a 20 x 12 m warehouse with docks, shelves, packing stations, a keep-out area and a 1.4 m doorway between the two halves. Driving costs battery and simulated time, faults block motion until the right node is restarted, and a safety margin set too wide closes the doorway. The same seed always gives the same world, so the end state of a run can be checked exactly.
Related MCP server: permitd MCP Server
Results so far
robomcp-check starts the server as a subprocess and talks to it over stdio like any MCP
client. All 19 scripted calls return the expected outcome: reads succeed, motion without an
operator returns APPROVAL_REQUIRED, a parameter outside the allow-list and releasing an
emergency stop return PERMISSION_DENIED even with approval waived, and malformed calls are
rejected before the policy sees them. With approval waived, a delivery (pick, drive through
the doorway, drop) ends with the item at the packing station and nine audit records for
nine calls. Full table: reports/server_check.md.
Documentation search, on the 61 answerable questions written for robotics-docs-rag, over 2,730 sections:
Counted as a hit | Hit@1 | Hit@5 | Hit@10 | MRR@10 |
Section from a gold page containing an answer phrase | 0.410 | 0.672 | 0.787 | 0.526 |
Any section from a gold page | 0.574 | 0.754 | 0.820 |
This is plain BM25, chosen so the server needs no embedding model. For 13 of the 61
questions no relevant section is in the top 10, so an agent will have to rephrase and search
again; whether it does is part of what the evaluation will measure. The same questions sent
through the search_docs tool over MCP give identical scores. A round trip takes about
0.5 ms for a fleet read and 3 ms for a search (median, Apple M5), which says the protocol
adds little; it says nothing about a real robot. Details:
reports/docs_search.md.
Repository structure
agent-mcp-robotics/
├── configs/
│ ├── default.yaml pinned corpus commit, world seed, paths
│ └── policy.yaml tiers -> allow / ask / deny, argument limits
├── src/robomcp/
│ ├── world.py, planner.py simulated fleet, A* on a grid with inflated keep-out areas
│ ├── download.py ROS 2 docs + question set at pinned commits, SHA-256 recorded
│ ├── rst.py, docs.py RST -> sections, BM25 index, snippets, paged reads
│ ├── tools.py 16 tools: tier, JSON Schema, handler
│ ├── permissions.py policy loading and decisions
│ ├── executor.py validate -> permit -> run -> audit
│ ├── server.py MCP server over stdio
│ ├── check.py, docs_eval.py the two reports
├── reports/ server_check, docs_search (.md and .json)
└── tests/ fixed world, tiny synthetic docs; no network, no modelsGetting started
uv venv --python 3.12 && source .venv/bin/activate
uv pip install -e ".[dev]"
robomcp-download # ROS 2 docs (text only) and the question set, ~40 MB download
robomcp-build-index # artifacts/docs_sections.jsonl
robomcp-docs-eval # reports/docs_search.md
robomcp-check # reports/server_check.md
pytest -qTo use the server from an MCP client, register it as a stdio server:
{
"mcpServers": {
"robomcp": {
"command": "/path/to/agent-mcp-robotics/.venv/bin/robomcp-server",
"args": ["--project-dir", "/path/to/agent-mcp-robotics"]
}
}
}With the shipped policy the client can read everything and stop robots; motion and
parameter changes return APPROVAL_REQUIRED because a stdio server has no operator
attached. --on-ask allow waives that for experiments; denied tiers and argument limits
still hold.
Design decisions
Tools are defined once and used both in-process and through MCP, so tests and the server cannot drift apart.
Permission lives in the executor, outside the model. The model sees a refusal with a code and a reason; it never sees or edits the policy.
Argument limits are checked before anyone is asked for approval, so a hasty "yes" cannot widen what is permitted.
Refusals and failures are ordinary tool results with
is_errorset, not protocol errors, so a model can read them and try something else.Search returns short snippets and section ids; full text is read one page at a time. That keeps untrusted text out of the context unless the agent asks for it.
License
MIT. The ROS 2 documentation is CC BY 4.0 and is downloaded, not redistributed.
Available Tools
16 toolsclear_emergency_stopADestructive
Release an emergency stop so the robot can move again.
Inputs: robot_id (required).
dockBDestructive
Drive a robot to a free charging dock and charge it to 100 %.
Inputs: dock (required), robot_id (required).
drop_itemADestructive
Unload the carried item at the station or shelf the robot is standing at.
Inputs: robot_id (required).
emergency_stopAIdempotent
Stop a robot immediately. It will not move until the stop is cleared.
Inputs: robot_id (required).
get_paramsCRead-onlyIdempotent
Navigation parameters of a robot with their allowed ranges.
Inputs: robot_id (required).
get_robot_stateCRead-onlyIdempotent
State and parameters of one robot.
Inputs: robot_id (required).
list_locationsARead-onlyIdempotent
Named locations (docks, shelves with their items, stations with what was delivered) and zones (keep-out areas, speed limits).
Inputs: no named parameters.
list_robotsARead-onlyIdempotent
List every robot with its status, position, battery and payload.
Inputs: no named parameters.
pick_itemBDestructive
Load an item from the shelf the robot is standing at.
Inputs: item (required), robot_id (required).
plan_routeARead-onlyIdempotent
Plan a trip without moving: distance, duration, battery needed and whether the robot would arrive above the battery reserve.
Inputs: goal (required), robot_id (required).
read_diagnosticsBRead-onlyIdempotent
Most recent diagnostic messages of a robot, oldest first.
Inputs: robot_id (required), limit.
read_doc_sectionARead-onlyIdempotent
Read one documentation section, up to 2000 characters per call; pass next_offset to continue a long section.
Inputs: section_id (required), offset.
restart_nodeA
Restart one software node on a robot. Clears a fault caused by that node.
Inputs: node (required), robot_id (required).
search_docsARead-onlyIdempotent
Search the ROS 2 documentation. Returns section ids with a short snippet; read a section with read_doc_section before relying on it.
Inputs: query (required), k.
set_paramC
Change one navigation parameter of a robot.
Inputs: name (required), value (required), robot_id (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 16 tools
Most tools map to a distinct resource+action: fleet listing vs single-robot state, plan_route (dry-run) vs navigate_to (execute), set_param vs get_params, emergency_stop vs clear_emergency_stop, and search_docs vs read_doc_section are all clearly separated by their descriptions. Minor overlap between get_robot_state ("state and parameters") and get_params, and between list_locations (which also reports zones) and the absent per-location getter, but boundaries remain workable.
Predominantly consistent snake_case verb_noun pattern (list_robots, get_robot_state, set_param, restart_node, pick_item, drop_item, read_diagnostics, search_docs). A few deviations break the verb_noun form: emergency_stop is a bare noun phrase and dock/navigate_to use a verb with a preposition, but nothing is ambiguous or mixed-convention in casing.
16 tools is just above the comfortable band but each earns its place across four coherent areas: fleet/state queries, movement and manipulation, parameters/diagnostics, and ROS 2 documentation lookup. No obvious redundant or filler tools, so the slightly high count reflects genuine domain breadth rather than padding.
Core robot lifecycle is well covered: observe state/params/diagnostics, plan and execute motion, dock and charge, pick/drop payloads, emergency stop with a paired clear, and node restart. Gaps are modest: there is no way to abort an in-flight navigation except emergency stop, and locations/zones are read-only (no create/edit of docks, shelves or keep-out zones).
Maintenance
Related MCP Connectors
Runtime permission, approval, and audit layer for AI agent tool execution.
Authorize AI agent tool calls before they run: policy-as-code, human approval, signed receipts.
Governed autonomous-agent platform: HITL approvals, budget gates, audit chain, effect ledger.
Build, validate, and deploy multi-agent AI solutions from any AI environment.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables controlling robots in ROS environments through natural language, supporting topics, services, actions, and GUI tools.2436MIT
- AlicenseNot gradedqualityCmaintenanceGates agent tool execution with human approval, audit trails, and replay-resistant permits, enabling safe use of tools in agent loops.MIT
- FlicenseNot gradedqualityCmaintenanceEnables controlled AI-agent access to enterprise-shaped tools with a deny-by-default gated write path, human approval, dry-run execution, and append-only audit logging.1-
- AlicenseAqualityBmaintenanceEnables LLM coding agents to inspect, control, and verify remote ROS2 robotics applications without a local ROS2 installation, supporting topics, services, actions, parameters, TF transforms, and automated test suites.16Apache 2.0