scene_service.mcp_tools

FastMCP tool definitions — two read-only handlers, that’s it.

list_objects() → flat list of every object in the registry goal_near(object_id) → reachable approach pose for a physical object goal_room(room_id) → reachable pose inside a room polygon

Writes happen on the ingest path (perception → registry); these handlers only read. Inputs are codegen-derived ROS dataclasses (semantic_map_mcp.*); the @mcp_contract decorator turns each one into a JSON-schema-typed MCP tool that Pilot discovers via atlas.

Functions

attach_scene_graph_store(store)
attach_state(*, registry[, hub])
get_object_context(req)	Return a single object's scene graph node, its direct relations, and nearby objects sorted by distance.
get_scene_graph(_req)	Return the current scene graph snapshot — all stable nodes with captions and their LLM-inferred spatial relations.
goal_near(req)	Find a navigation-safe approach pose near a physical scene object.
list_objects(_req)	Return every object the scene registry currently believes exists, plus room annotations, as a flat list.
list_relations(req)	List scene graph edges, optionally filtered by relation type.

scene_service.mcp_tools.attach_annotation_store(store: AnnotationStore | None) → None

scene_service.mcp_tools.attach_scene_graph_store(store: SceneGraphStore) → None

scene_service.mcp_tools.attach_state(*, registry: ObjectRegistry, hub=None) → None

async scene_service.mcp_tools.get_object_context(req: GetObjectContext_Request) → GetObjectContext_Response

Return a single object’s scene graph node, its direct relations, and nearby objects sorted by distance. Useful for Pilot to reason about one object’s context without fetching the full graph. Contract: robonix/system/scene/get_object_context.

async scene_service.mcp_tools.get_robot_context(_req: GetRobotContext_Request) → GetRobotContext_Response

Return one coherent map-frame spatial snapshot for Pilot.

async scene_service.mcp_tools.get_scene_graph(_req: GetSceneGraph_Request) → GetSceneGraph_Response

Return the current scene graph snapshot — all stable nodes with captions and their LLM-inferred spatial relations. Contract: robonix/system/scene/get_scene_graph.

async scene_service.mcp_tools.goal_near(req: GoalNear_Request) → GoalNear_Response

Find a navigation-safe approach pose near a physical scene object. Returns map-frame (x, y, yaw); pass to navigation/navigate.

Room annotations are deliberately not accepted. Resolve those through goal_room so the returned pose is constrained to the room polygon.

reachable=false when:

• the object ID is not in the registry;

• mapping is not publishing an occupancy grid; or

• no free cell exists within the target search radius.

Contract: robonix/system/scene/goal_near.

async scene_service.mcp_tools.goal_room(req: GoalRoom_Request) → GoalRoom_Response

Resolve a room annotation to a safe map-frame pose inside its polygon.

Use this for named rooms and user-defined regions before navigation/navigate. The result never falls outside the room polygon. Contract: robonix/system/scene/goal_room.

async scene_service.mcp_tools.list_objects(_req: ListObjects_Request) → ListObjects_Response

Return every object the scene registry currently believes exists, plus room annotations, as a flat list. Use this tool to discover stable object/room IDs before goal_near or goal_room. Use get_scene_graph only when object relationships are needed. Contract: robonix/system/scene/list_objects.

async scene_service.mcp_tools.list_relations(req: ListRelations_Request) → ListRelations_Response

List scene graph edges, optionally filtered by relation type. Pass empty relation string to get all edges. Contract: robonix/system/scene/list_relations.