MCP tool reference

The custom Beambot server exposes the tools below. The generic ROS MCP server handles general ROS operations, including action submission. A helper that returns task JSON does not itself run that task.

Most tools return JSON encoded as a string; ping returns plain text. Check the returned error or available fields for operation status. Each entry lists the signature and effects.

Implementation: src/beambot/mcp_server/beambot_mcp_server.py.

Named path defaults: DEFAULT_IMAGE_PATH = '/tmp/beambot_capture.jpg'; DEFAULT_ANNOTATED_PATH = '/tmp/beambot_detection.jpg'.

ping

Effect: Connectivity.

ping() -> str

Returns pong; does not initialize the ROS bridge.

stop_robot

Effect: Execution control.

stop_robot() -> str

Requests cancellation of all orchestrator goals. This is software cancellation, not a hardware emergency stop. It does not interrupt the motion in progress: cancellation takes effect after the active task or batch.

get_robot_state

Effect: ROS observation.

get_robot_state() -> str

Reports the configured beamline name, cached joint positions, gripper, and execution state. With ePick attached and a status received, it also includes vacuum_status. system_running means joint data has been received, not that every component is healthy. States include RUNNING, COMPLETING_TASK, PAUSED, CANCELING, FAULTED, and IDLE. Joint values are converted to degrees.

get_vacuum_status

Effect: ROS observation.

get_vacuum_status() -> str

Reports the latest ePick status and whether any status has arrived. This observation is distinct from the disabled orchestrator vacuum-loss abort path.

get_saved_poses

Effect: File read.

get_saved_poses(filter: str='') -> str

Returns pose names and six-joint degree arrays, optionally filtered by a case-insensitive name substring.

save_pose

Effect: File write.

save_pose(name: str, joints_deg: list=None, description: str='') -> str

Adds or overwrites a pose. Explicit joints are converted to six numeric degree values; omitted joints are read from the robot. The description parameter is accepted but not stored.

delete_pose

Effect: File write.

delete_pose(name: str) -> str

Removes a named pose from the registry, or returns an error when it is absent.

set_cup_profile

Effect: Runtime setting.

set_cup_profile(name: str) -> str

Sets the orchestrator’s cup_profile ROS parameter. Setting the parameter does not itself rebuild the model. Because the cup profile is part of the model identity, the next ePick goal relaunches MoveIt with the new geometry.

capture_image

Effect: Camera operation / file write.

capture_image(
    camera: str = 'zivid',
    mode: str = '3d',
    save_path: str = DEFAULT_IMAGE_PATH,
    timeout: float = 30.0,
) -> str

Triggers Zivid capture or reads the available camera stream; saves an image. For Zivid, both modes call /capture; mode=3d additionally waits for a point cloud. Other mode strings skip that wait; they do not select the separate 2D capture service. Camera support still depends on the deployed driver.

detect_objects

Effect: Image analysis / file write.

detect_objects(
    method: str = 'hsv_color',
    camera: str = 'zivid',
    hue_low: int = 100,
    hue_high: int = 130,
    sat_min: int = 80,
    val_min: int = 80,
    min_area: int = 200,
    marker_ids: str = '',
    yolo_model: str = 'yolov8n.pt',
    yolo_confidence: float = 0.25,
    yolo_classes: str = '',
    transform_to_base: bool = True,
    save_path: str = DEFAULT_ANNOTATED_PATH,
) -> str

Processes the last image using HSV, ArUco, or YOLO detection and writes an annotated image when something is detected. The cached RGB image is converted to BGR before YOLO inference. Optional 3D conversion uses the point cloud and TF. This does not submit a motion task.

detect_sample_yolo

Effect: Image analysis / file write.

detect_sample_yolo(
    camera: str = 'zivid',
    confidence: float = 0.5,
    save_path: str = '/tmp/sample_detection_yolo.jpg',
) -> str

Runs the sample detector on the last image, derives available 3D coordinates, and writes an annotation. Requires its model and camera data.

get_point_3d

Effect: Point-cloud analysis / file write / optional UI.

get_point_3d(
    pixel_x: int,
    pixel_y: int,
    camera: str = 'zivid',
    transform_to_base: bool = True,
    search_radius: int = 10,
    confirm: bool = True,
    save_path: str = '/tmp/beambot_point3d.jpg',
) -> str

Looks up a pixel in the last point cloud, optionally confirms selection in a UI, and can transform to base_link. A successful lookup saves an annotated image to save_path, including when confirm=False. Search radius supports finding a nearby valid point; no robot movement is submitted.

get_tf_transform

Effect: ROS observation.

get_tf_transform(
    source_frame: str = 'flange',
    target_frame: str = 'base_link',
    timeout: float = 2.0,
) -> str

Returns translation, quaternion, degree RPY, and a 4×4 matrix for source_frame → target_frame. The default source is flange; do not interchange flange and tool0 orientation conventions.

get_recent_logs

Effect: File read.

get_recent_logs(severity: str='ERROR', logger: str='', count: int=30) -> str

Filters the tail of /tmp/beambot_launch.log by severity and logger prefix. Returns newest matching records first. A different launch method may not create this file.

vision_target

Effect: Task builder.

vision_target(
    target_name: str,
    element_index: int = 0,
    row: int = -1,
    col: int = -1,
    tag_id: int = -1,
) -> str

Returns task_json for a configured offset or grid target. It does not execute it. Grid indices are zero-based; explicit row and column take precedence over element_index. Grid validation and expansion use the same helper as pickup task macros.

pickup_tip

Effect: Task builder.

pickup_tip(tip_index: int=0, row: int=-1, col: int=-1) -> str

Builds a tip_rack task using vision_target’s helper. The MCP request and parser macro use different interfaces but share grid expansion. It does not execute the returned JSON.