Skip to main content
Glama
hieutachi

rosbridge-mcp

by hieutachi

rosbridge-mcp

CI License: MIT Python 3.10+

rosbridge-mcp는 Model Context Protocol 서버로, AI 에이전트(Claude Desktop, Cursor, VS Code 및 기타 MCP 클라이언트)를 표준 rosbridge v2 프로토콜(WebSocket + JSON)을 통해 ROS 2를 실행하는 로봇에 연결합니다. 로봇 또는 ROS 머신에서 rosbridge_server를 실행합니다. 이 MCP 서버는 네트워크를 통해 여기에 연결되며, AI가 토픽을 관찰하고, ROS 그래프와 TF 트리를 검사하고, 로봇의 카메라를 통해 보고, 메시지를 게시하고, 서비스를 호출하고, ROS 2 액션을 구동할 수 있도록 하는 11개의 도구를 제공합니다. AI 클라이언트를 실행하는 머신에 ROS 설치가 필요하지 않습니다.

아키텍처

+--------------------+   stdio (MCP)   +----------------+   WebSocket/JSON   +------------------+   DDS   +---------+
|  AI client         | <-------------> | rosbridge-mcp  | <----------------> | rosbridge_server | <-----> |  ROS 2  |
|  (Claude, Cursor,  |                 |  (this server) |    rosbridge v2    |  (on the robot)  |         |  graph  |
|   VS Code, ...)    |                 |                |      protocol      |                  |         |         |
+--------------------+                 +----------------+                    +------------------+         +---------+

Related MCP server: ROS2 MCP Server

빠른 시작 (60초)

pip install git+https://github.com/hieutachi/rosbridge-mcp.git

또는, 게시 후: pip install rosbridge-mcp (PyPI — 곧 제공 예정).

MCP 클라이언트 구성에 추가합니다 (정확한 파일 위치는 아래 클라이언트별 가이드 참조):

{
  "mcpServers": {
    "rosbridge": {
      "command": "rosbridge-mcp",
      "env": { "ROSBRIDGE_URL": "ws://<robot-ip>:9090" }
    }
  }
}

그런 다음 에이전트에게 물어보세요: "로봇에 어떤 토픽이 있나요?"

경로 선택

자신에게 맞는 가이드를 선택하세요 — 각 가이드는 독립적이므로 먼저 이 README의 나머지 부분을 읽을 필요가 없습니다:

귀하가...

가이드

Claude Desktop 사용자 — Claude에서 로봇과 대화하고 싶음

docs/claude-desktop.md

Cursor 또는 VS Code 사용자 — 에디터 내에서 로봇 도구를 사용하고 싶음

docs/cursor-vscode.md

ROS 초보자, 아직 로봇 없음 — 시뮬레이터 또는 Docker로 모든 것을 시도, 하드웨어 불필요

docs/simulator-quickstart.md

실제 로봇 연결 — LLM을 하드웨어 근처에 두기 전 안전 점검 목록

docs/real-robot-safety.md

개발자 — 기여, 도구 추가, 또는 코드 이해를 원함

docs/development.md

도구

총 11개의 도구. 모든 도구는 JSON을 반환합니다. 메시지 및 인자 페이로드는 rosbridge에서 사용하는 ROS 메시지의 동일한 JSON 표현을 사용합니다 (필드 이름은 .msg/.srv/.action 정의와 일치).

도구

기능

변경 여부?

list_topics

모든 토픽 + 메시지 유형

아니오

list_nodes

모든 실행 중인 노드

아니오

list_services

모든 사용 가능한 서비스

아니오

get_topic_snapshot

토으로부터 라이브 메시지 수집

아니오

get_tf_tree

TF 좌표계 트리 스냅샷

아니오

get_camer_image

하나의 카메라 프레임을 base64로 가져오기

아니오

get_connecton_status

연결 + 읽기 전용 상태

아니오

publish_message

토픽에 메시지 게시

예

call_service

모든 ROS 서비스 호출

예 (읽기 전용은 /rosi 읽기 전용의 허용 목록을 허용)

send_ction_goal

ROS 2 액션 목료를 보내고 결과를 기다림

예

cancel_ction_goal

진행 중인 액션 목표 취소

예

list_topics n

모든 토과 해당 메시지 유형을 리스트합니다. 파라미터 없음.

{"topics": [
  {"name": "/chatter", "type": "std_msgs/msg/String"},
  {"name": "/cmd_vel", "type": "geometry_msgs/msg/Twist"},
  {"name": "/scan",    "type": "sensor_msgs/msg/LaserScan"}
]}

list_nodes

모든 실행 중인 노드를 나열합니다. 파라미터 없음.

{"nodes": ["/talker", "/listener", "/rosapi"]}

list_services n

모든 사용 가한 서비스를 리스트합니다. 파라미터 없음.

{"services": ["/rosapi/topics", "/rosapi/nodes", "/reset_odometry"]}

get_topic_snapshot n

토픽에 구독하고, 메시지를 수집하고, 구독을 취소합니다. 파라미터: topic (필수), count (기본값 1), timeout 초 (기본값 5.0), msg_type (선택사항, 일반적으로 rosbridge가 자동 감지).

입력: {"topic": "/chatter", "count": 2, "timeout": 3.0}

{"topic": "/chatter", "requested": 2, "received": 2,
 "messages": [{"data": "Hello World: 41"}, {"data": "Hello World: 42"}],
 "timed_out": false}

토이 조용할 경우 received는 requested보다 작고 timed_out은 true입니다 — 도구는 timeout보다 오래 걸리지 않습니다.

publish_message (변경) n

토을 광고하고 하나의 JSON 메시지를 게시합니다. 파라미터: topic, msg_type (전체 ROS 2 유형, 예: geometry_msgs/ms/Twist), message (유형과 일치하는 JSON 객체).

입력:

{"topic": "/cmd_vel", "msg_type": "geometry_msgs/msg/Twist",
 "message": {"linear": {"x": 0.1, "y": 0.0, "z": 0.0},
             "angular": {"x": 0.0, "y": 0.0, "z": 0.2}}}

출력: {"published": true, "topic": "/cmd_vel", "type": "geometry_msgs/msg/Twist"}

call_service (변경) n

모든 ROS 서비스를 호출합니다. 파라미터: service (필수), args (JSON 객체, 기본값 {}), timeout 초 (기본값 10.0). n 입력: {"service": "/rosapi/topic_type", "args": {"topic": "/scan"}} n GXP9 n 실패 시 도구는 {"success": false, "error": "..."}을 반환하며 예외를 발생시키지 않습니다. n

send_action_goal (변경) n

ROS 2 액션 서버(네비게이션, 암 모션 등)에 목표를 보냅니다. 파라미터: action_name, action_type (전체 유형은 /action/ 포함, 예: nav2_msgs/ction/NavigateToose), goal (JSON 객체, 기본값 {}), timeout 초 (기본값 30, 최대 120으로 제한), wait_for_result (기본값 true). n 입력: {"action_name": "/fibonacci", "action_type": "test_msgs/action/Fibonacci", "goal": {"order": 5}} n GXP10 n wait_for_result: false인 경우 도구는 즉시 {"goal_id": ..., "result_pending": true}를 반환합니다 — 나중에 목표를 중지하려면 해당 goal_id를 cancel_action_goal에 전달하세요. ROS 2 액션 지원이 포함된 rosbridge_suite 버전이 필요하며, 오래된 rosbridge에 대해 도구는 대신 업그레이드를 권장하는 오류를 반환하고 중단되지 않습니다.

cancel_action_goal (변경) n

이전에 보낸 액션 목표를 취소합니다. 파라미터: action_name, goal_id (send_action_goal에서 가져옴).

출력: {"cancel_sent": true, "action": "/navigate_to_pose", "goal_id": "send_action_goal:7"}

get_tf_tree n

/ff와 tf_static에 잠간 청취하여 로의 T (좌표 변환) 트리 스냅샷을 가져옵니다. 파라미터: timeout 초 (기본값 2.0, 최대 10으로 제한).

{"frame_count": 3,
 "frames": {
   "base_link": {"parent": "odom", "translation": {"x": 1.0, "y": 0.0, "z": 0.0},
                  "rotation": {"x": 0, "y": 0, "z": 0, "w": 1}, "source": "dynamic"},
   "laser":     {"parent": "base_link", "...": "...", "source": "static"}},
 "tree": {"odom": ["base_link"], "base_link": ["laser"]},
 "roots": ["odom"]}

get_camera_image

카메라 토픽에서 base64로 하나의 프레임을 가져와 시각 기능이 있는 모델이 로이 보는 것올 볼 수 있게 합니다. 파라미터: topic (sensor_msgs/ms/CompressedImage 토 선호, 예: /camera/image_raw/compressed), timeout 초 (기본값 5.0, 최대 30으로 제한).

출력: {"topic": ..., "format": "jpeg", "data_base64": "...", "size_bytes": 51234} (원시 Image 토은 추가로 width/height/encoding 반환). 4 MB 초과 프레임은 반환되지 않으며 도구는 메타데이터와 압축 토을 제안하는 오류로 응답합니다.

get_connection_status n

연결 상테와 읽기 전용 모도를 보고합니다. 파라미터 없음.

GXP12 n

예시 대화

당신: 로이 지금 무었을 보고 있나요?

에이전트: (list_topics 호출, sensor_msgs/msg/LaserScan 유형의 /scan 찾음, 그 다음 get_topic_snapshot을 {"topic": "/scan", "count": 1}로 호출) n> 레이저 스너는 360개 범위 읽기을 보고합니다. 가장 가까운 장에물은 왼른 쪽 약 90°에서 약 0.4 m 떨어져 있습다. 정면 쪽은 적어도 2.5 m 동안 막혀 있습다.

당신: 좋아요, 잠시 동안 천천히 앞으로 주행하세요.

에이전트: (publish_message를 {"topic": "/cmd_vel", "msg_type": "geometry_msgs/msg/Twist", "message": {"linear": {"x": 0.1}, "angular": {"z": 0.0}}}로 호출) 0.1 m/s 전진 속도 명령을 게시했습니다. 중단하고 싶을 때 알려주시면 속도를 0으로 게시하겠습니다.

비전 및 임베디드 AI를 위한

두 가지 읽기 전용 도구는 비전-언어 모델을 로봇의 물리적 현실에 근거시키기 위해 특별히 존재합니다:

  • **get_camera_image**는 실제 카메라 프레임을 base64로 반환합니다 — 시각 기능이 있는 모델(Claude, GPT-4o, 또는 VLA 정책 프론트엔드)은 결정을 내리기 전에 문자 그대로 로봇의 카메라를 통해 볼 수 있습니다.

  • **get_tf_tree**는 모델에 로봇의 공간적 골격을 제공합니다 — 어떤 프레임(map, odom, base_link, camera, gripper)이 존재하고 서로 어떻게 배치되어 있는지.

get_topic_snapshot(라이다, 주행 거리, 조인트 상태) 및 send_action_goal(네비게이션, 조작)과 결합되면, 모델 측에 ROS 설치 없이, 일반 WebSocket을 통해 비전 및 동작 에이전트가 필요로 하는 관찰 → 추론 → 수행 을 커버합니다. 두 지각 도구 모두 읽기 전용 모드에서 작업하므로 "보고 만지지 않는" 에이전트를 안전하게 실행할 수 있습다.

구정

환경 변수

기본값

설명

ROSBRIDGE_URL

ws://localhost:9090

rosbridge 서버의 WebSocket URL

ROSBRIDGE_MCP_READONLY

false

변환 도구 거부 (안전 참조)

n

안전

언어 모델이 물리적 로봇에 /cmd_vel을 게시하도록 하는 것음 실체적 위험입니다. ROSBRIDGE_MCP_READONLY=true로 설정하여 읽기 전용 모드로 실행하세요: publish_message, send_action_goal, cancel_action_goal이 거부되며, call_service는 알려진 읽기 전용 /rosapi 인트로스펙션 서비스(토픽, 노드, 서비스, 유형, get_param, get_time, ...)의 고정된 허용 목록만 허용합니다 — 목록에 없는 항목(알려지지 않은 향후 /rosapi 서비스 포함)은 거부됩니다. 읽기 전용 지각 도구(get_topic_snapshot, get_tf_tree, get_camera_image)는 계속 작동합니다. 실제 하드웨어에서는 읽기 전용 모드로 시작하는 것을 강력히 권장합니다 — 전체 실제 로봇 안전 점검 목록 및 SECURITY.md의 배포 보안 모델을 참조하세요. n

개인정보 보호 및 법적 고지

텔레메트리 없음, 데이터 수집 없음. 감사 완료 (2026-08): 이 패키지가 여는 유일한 네트워크 연결은 사용자가 구성한 ROSBRIDGE_URL에 대한 WebSocket입니다 — 분석, 전화 홈, 크래시 보고, 숨겨진 HTTP 호출이 없으며, 코드에는 메시지 내용을 디스크에 로깅하는 내용이 전혀 없습니다. 번들된 모의 서버는 127.0.0.1에만 바인딩됩니다. 도구가 반환하는 로봇 데이터는 전적으로 MCP 클라이언트로 전송되며(이 데이터는 선택한 LLM으로 전홥됨 — 그 부문은 귀하의 통제 하에 있씁, 당신의 통제 아님). n 라이선스 준수. 모든 런타임 및 전이 의존성은 이 프젝트의 MIT 라이선스와 호환되는 라이선스를 가짐니다 — 직접: fastmcp (Apache-2.0), websockets (BSD-3-Clause); 키 전이: mcp (MIT), pydantic (MIT), starlette (BSD-3-Clause), httpx (BSD-3-Clause), anyio (MIT), cryptography (Apache-2.0/BSD-3). 하나의 전이 의존성인 certifi는 MPL-2.0입니다 — 파일 수준의 카피레프트로 certifi 자체 파일의 수정에만 적용되며 MIT 사용 및 재배포와 호환됩니다. 의존성 트리에 GPL/AGPL/독점 코드가 전혀 없으며, 이 저장소의 모든 코드는 이 프로젝트를 위해 작성된 독창적인 작업입니다.

FAQ

AI 클라이언트가 실향되곳 곳에 ROS가 설치되어 야 하나요? 아니오. Python 3.10+만 필요합니다. ROS 및 rosbridge는 로봇(Docker 내, 또는 시뮬레이터)에서 실행됩니다. 이 서버는 WebSocket을 통해 이들과 통신합니다.

ROS 1에서도 작동하나요? rosbridge v2 프로토콜은 동일하므로 기본 작업은 ROS 1 rosbridge_server에서도 작동합니다 — ROS 1 유형 이름(std_msgs/String)을 사용하세요. CI에서는 ROS 2만 테스트됩니다.

에이전트가 연결할 수 없다고 합니다. rosbridge가 실행 중인지 확인하세요(ros2 launch rosbridge_server rosbridge_websocket_launch.xml), ROSBRIDGE_URL이 올바른 호스트/포트를 가리키고 있는지, 그리고 포트 9090에 접근 가능한지(방화벽) 확인하세요. docs/의 각 가이드에는 문제 해결 섹션이 있습니다.

로봇이나 시뮬레이터 없이 시도할 수 있나요? 네 — python -m rosbridge_mcp.mock_server 9090을 실행하면 미리 정의된 토픽이 있는 가짜 rosbridge가 시작되며, 그런 다음 ROSBRIDGE_URL을 ws://localhost:9090으로 설정하세요.

내 데이터가 다른 곳으로 전송되나요? 서버는 사용자가 설정한 ROSBRIDGE_URL에만 연결됩니다. 토픽 데이터는 MCP 클라이언트로 반환되며, 클라이언트는 이를 사용자가 사용하는 LLM으로 전달합니다 — 센서 데이터를 적절히 처리하세요.

로드맵

단계별 목표, 산출물, 각 단계에 필요한 리소스가 포함된 단계별 계획: ROADMAP.md 참조. 주요 내용: v0.2 액션 클라이언트 + TF + 카메라 스냅샷(v0.2.0에서 완료), v0.3 HTTP 전송 + Docker 이미지 + rosbridge 인증/TLS, v0.4 다중 로봇 플릿 + MCP 리소스(URDF/맵), v1.0 안정적인 API + 공식 MCP 레지스트리 등록 + Gazebo/Isaac Sim 예제.

이 프로젝트 지원하기

rosbridge-mcp는 한 사람이 초기 단계에서 파트타임으로 구축하고 유지 관리합니다. 현재 존재하는 것은 실제로 작동하며 테스트되었습니다: 11개의 도구 — 토픽, 서비스, ROS 2 액션, TF, 카메라 스냅샷 포함; 43개의 자동화된 테스트가 모든 커밋마다 CI에서 실행됨; 5가지 사용자 경로에 대한 시나리오별 문서; 읽기 전용 안전 모드와 서비스 허용 목록; 감사된 제로 텔레메트리 코드베이스.

로드맵이 현실이 되기 위해 필요한 것, 솔직하게 말씀드리면:

  • v0.3 (배포 및 보안): 파트타임 개발 주, Docker 이미지 빌드를 위한 소규모 클라우드 VM 또는 자체 호스팅 러너, 그리고 가장 중요한 — rosbridge 인증/TLS 계층에 대한 보안 중심 검토자.

  • v0.4 (플릿): 2대 이상의 동시 실행 로봇 또는 시뮬레이터 인스턴스에 대한 액세스, 그리고 실제 로봇 연구소의 설계 피드백(학술 또는 산업 파일럿 파트너 찾고 있음).

  • v1.0 (안정성 및 생태계): 지속적인 유지 관리자 시간(분기당 주 2일 정도), Isaac Sim 검증을 위한 RTX급 GPU 워크스테이션 1대 — 전체 로드맵의 주요 하드웨어 요청 — 그리고 선택적으로 하드웨어 인더루프 CI를 위한 저가형 로봇(약 1~3천 달러).

도움을 주실 수 있는 방법(노력 순서대로):

  1. 저장소에 별표를 눌러주세요 — 가시성은 초기 프로젝트에 기여자를 얻는 데 실제로 도움이 됩니다.

  2. 로봇이나 시뮬레이터에서 시도해보고 ROS 배포판 + rosbridge 버전과 함께 이슈를 열어주세요 — 호환성 보고는 이 프로젝트를 견고하게 만드는 가장 저렴한 방법입니다.

  3. PR을 기여해주세요 — docs/development.md는 10분 안에 코드베이스를 설명하며, 모든 로드맵 항목은 클레임 가능합니다.

  4. 후원 또는 파트너십 — 연구소나 회사에서 시뮬레이터 시간, 하드웨어, GPU 워크스테이션, 또는 개발 자금을 제공할 수 있다면 github.com/hieutachi를 통해 연락주세요.

관련 자료

로봇 공학에 입문하는 경우, Robotics RL & UAV ebook은 저자가 작성한 강화 학습 및 UAV 로봇 공학을 다루는 동반 학습 자료입니다.

기여

기여는 환영합니다! CONTRIBUTING.md 및 개발 가이드를 참조하세요. 커밋에 서명(DCO)해 주세요.

라이선스

MIT — LICENSE 참조. 종속성 라이선스는 허용적이며 호환 가능합니다: fastmcp (Apache-2.0), websockets (BSD-3-Clause). GPL/AGPL 종속성 없음.


베트남어 요약

rosbridge-mcp는 AI 에이전트(Claude Desktop, Cursor, VS Code 등)와 rosbridge 프로토콜(WebSocket + JSON)을 통해 ROS 2를 실행하는 로봇을 연결하는 MCP 서버입니다. AI 클라이언트를 실행하는 머신에 ROS를 설치할 필요가 없습니다.

문서는 시나리오별로 나뉘어 있습니다 — docs/ 디렉토리에서 자신에게 맞는 가이드를 선택하세요:

  • Claude Desktop 사용 — Windows/macOS/Linux에서 단계별 JSON 구성

  • Cursor / VS Code 사용 — 편집기에서 mcp.json 구성

  • 로봇 없음 — Docker(ros:humble + rosbridge) 또는 TurtleBot3/Gazebo, 또는 포함된 모의 서버로 시험 실행

  • 실제 로봇 있음 — 안전 체크리스트: 먼저 ROSBRIDGE_MCP_READONLY=true를 활성화하고, /odom, /scan을 읽어 로봇을 이해한 후에 /cmd_vel 발행 권한을 여세요

  • 개발자 — 코드 아키텍처, 새 도구 추가 방법, 모의로 테스트 실행(ROS 필요 없음)

11개 도구: list_topics, list_nodes, list_services, get_topic_snapshot, publish_message, call_service, send_action_goal, cancel_action_goal, get_tf_tree, get_camera_image, get_connection_status. 실제 로봇으로 작업할 때 ROSBRIDGE_MCP_READONLY=true를 설정하여 모든 쓰기 작업(발행, 액션)을 차단하세요 — 읽기 도구(TF, 카메라, 토픽)는 정상 작동합니다.

저자의 동반 학습 자료: Robotics RL & UAV ebook — 강화 학습 및 UAV 로봇 공학에 관한 전자책.

Available Tools

11 tools
call_serviceA

Call any ROS service with JSON args and return the response values.

Rejected when ROSBRIDGE_MCP_READONLY is set, unless the service is on the fixed allowlist of known read-only /rosapi introspection services (topics, nodes, services, *_type, *_details, get_param, get_time, ...).

Args: service: Full service name, e.g. "/rosapi/topic_type" or "/reset_odometry". Discover names with list_services. args: JSON object matching the service request definition, e.g. {"topic": "/scan"} for /rosapi/topic_type. Default {}. timeout: Max seconds to wait for the response (default 10.0).

Returns {"service", "success": true, "values": {...}} on success, or {"service", "success": false, "error": "..."} on failure/timeout (with any related rosbridge status errors under "rosbridge_status").

ParametersJSON Schema
NameRequiredDescriptionDefault
argsNo
serviceYes
timeoutNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.6/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description bears full responsibility for behavioral disclosure. It explains readonly mode rejection, the return format (success vs failure with values/error/rosbridge_status), and that args are JSON. It does not explicitly flag potential side effects of calling a service, but given the generic nature, this is acceptable. The readonly note subtly suggests that some calls are destructive.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is tightly written. The first sentence states the core purpose immediately, followed by a critical usage note, then a clean Args/Returns block. Every sentence adds unique value; no filler or repetition. Length is appropriate for the tool's complexity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given zero annotations and zero schema-level descriptions, the tool description must stand alone. It covers: purpose, restricted-mode behavior, all three parameters (with defaults, format, examples), and the full return structure (success and failure cases). The presence of an output schema means return details are not required, but the description still enumerates them. Very complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must fully explain parameters. It does: service name with example, args as JSON object with example defaults, timeout as seconds with default. This goes well beyond what the bare schema provides (which only lists types and defaults). No redundancy; all param info in description is additive.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description starts with a clear verb-resource pair: 'Call any ROS service with JSON args.' This precisely defines the action and target. It distinguishes from sibling tools (list_*, get_*, publish_message, send_action_goal) by focusing on service calling rather than introspection, publishing, or action management.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly states when the tool is rejected (readonly mode unless allowlisted) and suggests using list_services to discover service names. However, it does not directly compare against siblings like publish_message (which uses topics) or send_action_goal (actions), leaving the agent to infer the appropriate tool based on service vs topic vs action distinction. A clear 'Use this for calling services, not for topics or actions' would elevate to 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

cancel_action_goalA

Cancel a previously sent ROS 2 action goal.

Rejected when ROSBRIDGE_MCP_READONLY is set.

Args: action_name: The action the goal was sent to, e.g. "/navigate_to_pose". goal_id: The goal_id returned by send_action_goal.

Returns {"cancel_sent": true, "action", "goal_id"}. The cancellation outcome (status "canceled") is reported by the action server via the goal's result. Requires rosbridge_suite with ROS 2 action support; on an older rosbridge the tool returns an error advising an upgrade.

ParametersJSON Schema
NameRequiredDescriptionDefault
goal_idYes
action_nameYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Given no annotations, the description takes on the transparency burden. It discloses the cancellation request, the asynchronous nature of the outcome, and the return value. It also mentions version requirements. However, it does not cover edge cases like already-completed goals.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise and front-loaded with the key purpose. It includes necessary details without redundancy. The structure is logical, though a slight trim could be possible without losing clarity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a two-parameter tool with no annotations, the description covers purpose, parameters, return value, and usage conditions. It is reasonably complete, though it could mention failure modes or prerequisites for the goal to be cancellable (e.g., goal must be active).

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so the description must explain parameters. It does so effectively: action_name is described with an example, and goal_id is linked to the send_action_goal tool's return value. This adds significant meaning beyond the schema's type-only definitions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Cancel a previously sent ROS 2 action goal.' It uses a specific verb and resource, and distinguishes itself from sibling tools like send_action_goal, which is the complementary action.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description specifies when the tool is rejected (when ROSBRIDGE_MCP_READONLY is set) and lists requirements (rosbridge_suite with action support). It provides context for use but does not explicitly mention alternatives or when not to use it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_camera_imageA

Grab one frame from a camera topic, for vision-capable models.

Read-only — works in readonly mode. Subscribes to topic, waits for one sensor_msgs/msg/CompressedImage (preferred) or sensor_msgs/msg/Image (raw) message, and returns the frame as base64. This is the bridge for VLM / vision-language-action workflows: the model can literally look through the robot's camera before deciding how to act.

Args: topic: Camera topic, e.g. "/camera/image_raw/compressed". Prefer a compressed topic — raw images are large and may exceed the size limit below. timeout: Max seconds to wait for a frame (default 5.0, clamped to at most 30.0).

Returns {"topic", "format" (e.g. "jpeg"), "data_base64", "size_bytes"}, plus "width"/"height"/"encoding" for raw images. Frames larger than 4 MB are not returned: the tool responds with an error suggesting a CompressedImage topic instead (raw metadata is still included).

ParametersJSON Schema
NameRequiredDescriptionDefault
topicYes
timeoutNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.8/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full behavioral burden. It discloses read-only nature, subscription behavior, message types (CompressedImage/Image), return format, size limit (4 MB), and error response behavior. This is comprehensive.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is moderately long but well-structured with Args and Returns sections. Every sentence adds operational detail (size limits, raw image metadata, readonly mode), making it appropriately sized.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (subscription, timeout, size handling, output schema), the description covers all operational aspects including error conditions and return payload, making it complete. The output schema is described in prose, which is acceptable.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has no descriptions and 0% coverage, so the description fully compensates. It explains topic with an example and guidance, and timeout with default and max clamp. Additionally, it documents the return structure.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with 'Grab one frame from a camera topic, for vision-capable models,' clearly stating the tool's function with a specific verb and resource. It distinguishes itself from sibling tools like get_topic_snapshot by emphasizing camera images and VLM workflows.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It provides clear context for when to use: 'This is the bridge for VLM / vision-language-action workflows' and advises 'Prefer a compressed topic.' However, it does not explicitly name alternative tools or exclusionary criteria, so it stops short of full when/when-not guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_connection_statusA

Report the current rosbridge connection status and readonly mode.

Takes no arguments. Returns {"url", "connected", "connected_since_unix", "active_subscriptions", "pending_service_calls", "readonly"}. The connection is opened lazily, so "connected" is false until another tool has been used. Check this first when other tools report errors.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must carry the full burden. It discloses the lazy connection behavior ('connected is false until another tool has been used') and lists the return fields. This adds significant behavioral context beyond a simple status check.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, front-loaded with purpose, and every sentence earns its place. The first sentence states the purpose, the second provides behavioral detail and usage guidance. No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has no parameters, low complexity, and an output schema exists (though not shown), the description covers purpose, behavior (lazy connection), return fields, and usage guidance. It is fully complete for an agent to select and invoke correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, so the baseline is 4. The description adds value by explaining the return fields and the lazy connection behavior, which goes beyond the empty schema. No parameter documentation is needed, but the description compensates by clarifying what the tool returns.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool reports the current rosbridge connection status and readonly mode. The verb 'report' and the resource 'connection status' are specific. It distinguishes from siblings like list_topics or publish_message, which serve different purposes.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description includes explicit guidance: 'Check this first when other tools report errors.' This tells the agent when to use the tool. It also notes that the tool takes no arguments, which is helpful. While it doesn't explicitly state when not to use alternatives, the context of diagnostic ordering is valuable.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_tf_treeA

Snapshot the robot's TF (coordinate transform) tree.

Subscribes briefly to /tf and /tf_static, merges every transform seen into a parent→child frame tree. Read-only — works in readonly mode. Useful for spatial reasoning: which frames exist (map, odom, base_link, camera, gripper, ...) and how they are connected.

Args: timeout: Seconds to listen for transforms (default 2.0, clamped to at most 10.0). Static transforms are latched and arrive immediately; dynamic ones need the robot to be publishing.

Returns {"frame_count", "frames": {child_frame: {"parent", "translation": {x,y,z}, "rotation": {x,y,z,w}, "source": "static"|"dynamic"}}, "tree": {parent: [children...]}, "roots": [frames with no parent seen]}. An empty tree usually means nothing publishes /tf on this robot (or the listen window was too short).

ParametersJSON Schema
NameRequiredDescriptionDefault
timeoutNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.6/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must carry the full burden. It explains that the tool subscribes briefly to /tf and /tf_static, merges everything into a parent-child tree, and is read-only. It also notes that static transforms are latched while dynamic ones need publishing. This fairly comprehensively discloses behavior. It loses one point because it doesn't mention if it unsubscribes after the timeout or any potential blocking behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with a summary line, a brief behavioral paragraph, a parameter section, and a detailed return value description. It is informative but not overly long. However, the return type description could be slightly more compact (e.g., the list of fields takes extra space). Still, every sentence earns its place. Minor deduction for lengthiness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite modest input schema (1 param, 0% coverage), the description is thorough. It explains the tool's behavior, the parameter semantics, the full return structure, and even includes a fallback ('empty tree means...'). The output schema exists and describes return fields, but the description adds context (e.g., what 'empty tree' means). The tool is simple (one param, one return), so the description is complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema provides only one parameter (timeout) with no description. The description adds significant meaning: the default is 2.0, it's clamped to at most 10.0, and it explains the semantics of listening duration in context of static vs dynamic transforms. This adds value beyond the schema. Baseline is 4 due to 0% schema coverage, and the description fully compensates.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb 'Snapshot' and a specific resource 'the robot's TF (coordinate transform) tree'. It clearly distinguishes itself from sibling tools like 'get_topic_snapshot', 'list_topics', and 'get_camera_image' by focusing on coordinate transforms and the robot's spatial structure, not just generic topics or images.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit guidance: it says 'Useful for spatial reasoning: which frames exist... and how they are connected.' It implies when to use (when frame hierarchy is needed) and implicitly not to use for other sensor data. It does not name alternative tools but the sibling list and the purpose make it clear it's the only tree-snapshot tool. The mention of 'Read-only — works in readonly mode' is a usage hint.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_topic_snapshotA

Read live data from a topic: subscribe, collect up to count messages (or until timeout seconds elapse), then unsubscribe.

Args: topic: Topic name including leading slash, e.g. "/scan" or "/odom". count: How many messages to collect (default 1, clamped to at most 100). Use more to observe a value changing over time. timeout: Max seconds to wait (default 5.0, clamped to at most 60.0). The tool never blocks longer than this, even on a silent topic. msg_type: Optional full message type, e.g. "sensor_msgs/msg/LaserScan". Usually omit it; rosbridge resolves the type of existing topics.

Returns {"topic", "requested", "received", "messages": [...], "timed_out", "timeout_s"}. If "timed_out" is true, nothing (or not enough) was published within the timeout — the topic may be silent, misspelled, or not exist. If the rosbridge connection drops mid-collection, the tool returns immediately with {"error", "connection_lost": true} instead of waiting out the timeout.

ParametersJSON Schema
NameRequiredDescriptionDefault
countNo
topicYes
timeoutNo
msg_typeNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.7/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description fully discloses behavior: subscribe-collect-unsubscribe lifecycle, clamping of count and timeout, never blocking longer than timeout, handling of connection loss, and return format including error fields. This exceeds the burden for a tool with no annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with a header and parameter list, but it is slightly verbose in places (e.g., the return format could be prepended). However, every sentence is informative and earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 4 parameters, no annotations, and an output schema (though not provided in input, but the description lists return fields), the description is complete. It covers all parameters, behavior, edge cases, and return structure.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 0% description coverage, but the description explains each parameter in detail: topic requires leading slash, count default and clamping, timeout behavior, and msg_type optionality. This adds significant meaning beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Read live data from a topic: subscribe, collect up to `count` messages (or until `timeout` seconds elapse), then unsubscribe.' This uses a specific verb and resource, and distinctively separates it from siblings like list_topics, publish_message, and call_service.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides usage guidance: 'Use more to observe a value changing over time' and explains when the tool may return empty (silent topic, misspelled, not exist). It does not explicitly compare to sibling tools, but the context is clear enough for an agent to decide when to use it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_nodesA

List all ROS nodes currently running on the robot.

Takes no arguments. Returns {"nodes": ["/talker", "/rosapi", ...]}. Useful to check whether an expected driver or controller is up.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full burden for behavioral disclosure. It states that the tool lists currently running nodes, returns a specific JSON structure, and takes no arguments. It does not mention potential side effects, permissions, or latency, but for a read-only list operation with no parameters, the given information is sufficient and transparent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise with two complete sentences plus a short example. Every sentence provides value: the first states the purpose, the second details the return format and confirms no arguments, and the third adds a practical use case. Zero waste.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has no parameters, a clear output schema, and a simple read-only purpose, the description is complete enough. It explains what the tool does, how to invoke it, what it returns, and when to use it. No gaps are evident.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Since there are zero parameters and the schema has 100% coverage, the description adds clarity by explicitly stating 'Takes no arguments.' The baseline is 4 as per guidelines for 0 parameters, and no further parameter documentation is necessary.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'List' and the resource 'ROS nodes currently running on the robot'. It distinguishes from siblings like list_topics and list_services by specifying the resource type (nodes vs topics/services).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly says 'Takes no arguments' which clarifies invocation. It also provides a use case: 'Useful to check whether an expected driver or controller is up.' However, it does not explicitly state when NOT to use it or mention alternatives among the siblings, though the tool name itself is distinctive enough.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_servicesA

List all ROS services currently available on the robot.

Takes no arguments. Returns {"services": ["/reset_odometry", ...]}. Use before call_service to find the exact service name.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.7/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full burden. It declares no arguments and specifies the return format (an object with a services array). While it doesn't explicitly state read-only behavior, listing services is inherently non-destructive. The example return value adds transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, each essential: what it does, what it takes, and how to use it. No wasted words, front-loaded with the main purpose. Ideal conciseness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple parameterless tool with an output schema, the description covers purpose, usage, and return structure completely. The example service name and the hint to use before call_service provide full context for the agent to decide and invoke.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has no parameters (100% coverage by default). The description confirms 'Takes no arguments,' which adds no extra meaning but meets the baseline for zero-parameter tools.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'List all ROS services currently available on the robot,' specifying both the verb (List) and the resource (ROS services). It effectively distinguishes from sibling tools like list_topics and list_nodes by naming the specific resource type.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit usage guidance: 'Use before call_service to find the exact service name.' This tells the agent when to invoke this tool and hints at a workflow sequence, making the purpose and timing unambiguous.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_topicsA

List all ROS topics currently known to the robot, with message types.

Takes no arguments. Returns {"topics": [{"name": "/scan", "type": "sensor_msgs/msg/LaserScan"}, ...]}. Call this first to discover what the robot exposes before subscribing or publishing.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description fully carries the burden of transparency. It explicitly states 'Takes no arguments' and describes the return format with an example, which is helpful for an AI. However, it does not mention side effects, rate limits, or access restrictions; a slight gap relative to a perfect score.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short sentences, no wasted words. Each sentence contributes: the first explains the action, the second clarifies arguments and output, the third provides usage guidance. Perfectly front-loaded with the key information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool is a simple, parameter-less discovery tool with a nested output schema and the description already includes an example of the return format, nothing is missing. The context signals confirm zero parameters and 100% schema coverage, so the description is fully complete for an AI agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has zero parameters and 100% description coverage (none needed), so baseline is 4. The description adds no parameter semantics (since none exist), but this is correct because there is nothing to add beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('list') and resource ('all ROS topics') while distinguishing from sibling tools (e.g., list_nodes) by specifying the output includes message types. This fully clarifies the tool's purpose.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description states when to use this tool ('Call this first to discover... before subscribing or publishing'), providing clear context. It does not explicitly exclude alternatives, but the guidance is strong enough for an AI to understand the primary use case.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

publish_messageA

Publish a JSON message to a ROS topic (advertises the topic first).

CAUTION: this can move a real robot. Rejected when ROSBRIDGE_MCP_READONLY is set. Prefer reading relevant sensor topics (e.g. /scan, /odom) before commanding motion, and publish zero velocity to stop.

Args: topic: Target topic, e.g. "/cmd_vel". msg_type: Full ROS 2 message type with the "/msg/" segment, e.g. "geometry_msgs/msg/Twist" or "std_msgs/msg/String". message: JSON object whose fields match the message definition, e.g. {"linear": {"x": 0.1, "y": 0.0, "z": 0.0}, "angular": {"x": 0.0, "y": 0.0, "z": 0.2}} for a Twist. Omitted fields default to zero/empty on the ROS side.

Returns {"published": true, "topic": ..., "type": ...} on success. The tool briefly waits for rosbridge 'status' errors after publishing; if rosbridge rejected the message (e.g. wrong msg_type), the result includes "rosbridge_warnings" — treat those as the publish having failed.

ParametersJSON Schema
NameRequiredDescriptionDefault
topicYes
messageYes
msg_typeYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.8/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must fully disclose behavior. It explains that the topic is advertised first, that the action is potentially destructive, that it waits briefly for rosbridge errors, and that failure results in rosbridge_warnings in the response. It also specifies the success return format. This is comprehensive and truthful.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is succinct and well-structured: a core action sentence, a caution block, then Args and Returns sections. Every sentence serves a purpose. It is front-loaded with the essential information—the action and the safety warning—and no extraneous text.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (3 required parameters, nested objects, no schema descriptions, no provided output schema), the description is remarkably complete. It covers the purpose, usage precautions, parameter formats and defaults, behavioral notes (advertisement, error handling), and return values. The AI agent has all necessary information to select and invoke this tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema provides no descriptions for its three parameters. The description compensates fully with detailed Args: topic gets an example path, msg_type gets the required ROS 2 format with examples, and message gets a full JSON example plus the important note that omitted fields default to zero/empty. This adds significant meaning beyond the raw schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a clear verb+resource: 'Publish a JSON message to a ROS topic (advertises the topic first).' It immediately distinguishes this tool from its siblings, which are primarily read-only (list_topics, get_topic_snapshot, etc.), by emphasizing that it can move a real robot.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides strong usage guidance: it warns that the tool can move a real robot, recommends reading sensor topics before commanding motion, advises publishing zero velocity to stop, and notes that it is rejected when ROSBRIDGE_MCP_READONLY is set. It could be more explicit about which sibling tools to use instead for reading (e.g., get_topic_snapshot), but the intent is clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

send_action_goalA

Send a goal to a ROS 2 action server via rosbridge.

CAUTION: actions typically make the robot move (navigation, arm motion). Rejected when ROSBRIDGE_MCP_READONLY is set.

Args: action_name: Action name, e.g. "/navigate_to_pose". action_type: Full action type with the "/action/" segment, e.g. "nav2_msgs/action/NavigateToPose". goal: JSON object matching the action's goal definition. Default {}. timeout: Max seconds to wait for the result when wait_for_result is true (default 30.0, clamped to at most 120.0). wait_for_result: If true (default), block until the action finishes and return its result. If false, return the goal_id immediately — use cancel_action_goal with that id to stop the goal later.

Returns, when waiting: {"action", "goal_id", "success", "status", "status_text" (succeeded/aborted/canceled/...), "values" (result fields), "last_feedback" (most recent feedback values, or null)}. When not waiting: {"action", "goal_id", "result_pending": true}.

Requires rosbridge_suite with ROS 2 action support (ops send_action_goal / cancel_action_goal). Against an older rosbridge the tool detects the rejected operation (via rosbridge status errors, or timeout as fallback) and returns an error advising to upgrade rosbridge_suite on the robot.

ParametersJSON Schema
NameRequiredDescriptionDefault
goalNo
timeoutNo
action_nameYes
action_typeYes
wait_for_resultNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.6/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden. It thoroughly discloses: the tool causes robot movement, is blocked by READONLY mode, requires specific rosbridge_suite support, handles errors with older bridges, details return structures for both blocking and non-blocking modes, and explains timeout clamping.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured: a brief purpose statement, a caution, parameter details with formatting, return value descriptions, and prerequisites. Every sentence adds necessary information without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity and the presence of an output schema, the description covers all essential aspects: purpose, parameters, return values, error scenarios, prerequisites, and practical usage notes. It is comprehensive and leaves no major gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, but the description fully compensates by explaining each parameter: action_name with example, action_type with full type format, goal as JSON object, timeout with default and clamping, and wait_for_result with behavior implications.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The tool's purpose is clearly stated: 'Send a goal to a ROS 2 action server via rosbridge.' The caution about robot movement and the contrast with siblings like cancel_action_goal, call_service, and publish_message provide strong differentiation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Some usage guidance is present: caution about robot movement, rejected when READONLY, and guidance on using cancel_action_goal when wait_for_result is false. However, there is no explicit comparison to sibling tools or advice on when to prefer this over other operations.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 11 tool updatesv0.2.0
    • First observedcall_service
    • First observedcancel_action_goal
    • First observedget_camera_image
    • First observedget_connection_status
    • First observedget_tf_tree
    • First observedget_topic_snapshot
    • First observedlist_nodes
    • First observedlist_services
    • First observedlist_topics
    • First observedpublish_message
    • First observedsend_action_goal

TDQS

A4.5/5.0

Scored across 11 tools

Disambiguation5/5

Each tool targets a distinct operation in the ROS ecosystem: listing resources, reading topic data, publishing, calling services, managing action goals, retrieving TF and camera data, and checking connection status. There is no overlap, and the descriptions clearly differentiate their purposes.

Naming Consistency4/5

The tools follow a verb_noun pattern, but use a mix of verbs: 'list_' for discovery, 'get_' for retrieval, and 'publish_', 'call_', 'send_', 'cancel_' for actions. While all are descriptive and readable, the lack of a single unified prefix across all tools keeps it from being a perfect 5.

Tool Count5/5

With 11 tools, the server is well-scoped for a ROS bridge interface. Each tool covers a distinct aspect of ROS interaction (topics, services, actions, TF, camera), and the number is neither too sparse nor overwhelming.

Completeness4/5

The tool surface covers core workflows: discovery, reading and writing topics, calling services, managing actions, and retrieving transforms and images. A minor gap is the lack of a dedicated tool to list available actions, but this can be partially achieved via list_services or documentation.

Maintenance

ActivitySlowing
ResponsivenessResponsive

Related MCP Connectors

Related MCP Servers

  • A
    license
    Not graded
    quality
    D
    maintenance
    Enables control of ROS/ROS2 robots through natural language commands by translating LLM instructions into ROS topics and services. Supports cross-platform WebSocket-based communication with existing robot systems without requiring code modifications.
    MIT
  • A
    license
    Not graded
    quality
    D
    maintenance
    Enables AI tools to interact with ROS2 robotics systems through natural language commands. Supports topic publishing/subscribing, service calls, message analysis, and auto-discovery of ROS2 interfaces for debugging and controlling robots.
    Mozilla Public 2.0
  • A
    license
    A
    quality
    D
    maintenance
    Enables controlling robots in ROS environments through natural language, supporting topics, services, actions, and GUI tools.
    24
    36
    MIT
  • A
    license
    Not graded
    quality
    D
    maintenance
    Enables large language models to interact with ROS robots seamlessly, allowing natural language control, real-time sensor monitoring, and autonomous task execution without modifying existing robot code.
    Apache 2.0