ros2_medkit_mcp copilot-instructions.md

Copilot Instructions

Project Overview

Python MCP (Model Context Protocol) server that wraps the ros2_medkit SOVD HTTP API, enabling LLM tools to interact with ROS 2 diagnostics. Provides 40+ tools for entity discovery, fault management, operations, configurations, and data access.

Architecture

src/ros2_medkit_mcp/
├── __init__.py
├── config.py           # Pydantic settings (base_url, timeout, auth)
├── models.py           # Pydantic models for tool arguments
├── client.py           # Async HTTP client (SovdClient) wrapping gateway API
├── mcp_app.py          # MCP server with tool definitions and dispatcher
├── server_stdio.py     # stdio transport entrypoint
└── server_http.py      # HTTP/SSE transport entrypoint

Key Components

SovdClient (client.py)

Async HTTP client using httpx for all gateway API calls:

class SovdClient:
    async def get_version(self) -> dict[str, Any]
    async def list_entities(self) -> list[dict[str, Any]]
    async def list_areas(self) -> list[dict[str, Any]]
    async def list_components(self) -> list[dict[str, Any]]
    async def list_faults(self, component_id: str) -> list[dict[str, Any]]
    async def create_execution(self, entity_id, operation_name, request_data, entity_type) -> dict
    async def get_execution_status(self, entity_id, operation_name, execution_id, entity_type) -> dict
    # ... 30+ more methods

MCP Tools (mcp_app.py)

Tools are registered via @mcp.tool() decorator and dispatched by name:

@mcp.tool()
async def sovd_version() -> str:
    """Get SOVD API version information."""
    ...

@mcp.tool()
async def sovd_entities_list(filter: str | None = None) -> str:
    """List all SOVD entities with optional filtering."""
    ...

@mcp.tool()
async def sovd_call_operation(
    entity_id: str,
    operation_name: str,
    request_data: dict | None = None,
    entity_type: str = "components"
) -> str:
    """Execute a SOVD operation (ROS 2 service call)."""
    ...