ros-mcp-server

ros-mcp-server is a TypeScript MCP server for controlling AMRs through a fixed MQTT contract. It does not talk to ROS2 directly. Instead, it sits between RCS, an external LLM bridge, and an AMR-side MQTT bridge.

Current flow:

User -> RCS chat UI -> ros-mcp-server (chat/tool orchestration) -> Ollama -> robot tools -> MQTT Broker -> AMR MQTT Server -> ROS2 Humble/Nav2

Architecture

This MVP combines two roles:

• MCP tool server for robot actions
• RCS-facing orchestration entry point via the chat tool

RCS remains a thin chat UI:

• the operator types natural-language requests
• RCS forwards them to MCP chat
• ros-mcp-server calls a local or network LLM bridge
• the LLM decides whether robot tools are needed
• tool results are folded into the final Korean response

The server is split into four layers:

• rms_mcp_server: MCP server creation, chat orchestration, and the WebSocket transport exposed at ws://127.0.0.1:3001/mcp
• rms_mqtt: MQTT connection management, protocol loading, symbolic topic resolution, and request-response helpers
• rms_core: shared config, logger, types, and error classes
• rms_utils: low-level JSON and timeout helpers

The MQTT topic contract is defined in editable JSON at rms_mqtt/protocols/amr-mqtt-protocol.json. MCP tools resolve symbolic keys such as navigation.command instead of hardcoding topic strings.

Folder Structure

ros-mcp-server/
  package.json
  tsconfig.base.json
  .env.example
  README.md

  rms_mcp_server/
    src/
      index.ts
      orchestrator.ts
      server.ts
      transport.ts
      tooling.ts

  rms_mqtt/
    src/
      mqttClient.ts
      protocolLoader.ts
      topicResolver.ts
      requestResponse.ts
    protocols/
      amr-mqtt-protocol.json

  rms_core/
    src/
      config.ts
      logger.ts
      types.ts
      errors.ts

  rms_utils/
    src/
      json.ts
      timeout.ts
    scripts/
      pkill.sh

Install

npm install

Run

npm run dev

To start both the RMS server and a local Ollama runtime together:

npm run dev:all

dev:all checks whether Ollama is already available at the configured bridge URL. If not, it tries to start ollama serve first and then launches the RMS dev server.

The MCP WebSocket endpoint will be available at:

ws://127.0.0.1:3001/mcp

Configuration

Copy .env.example to .env and adjust values as needed.

Core values:

• MQTT_BROKER_URL: broker endpoint used by the MQTT client
• MQTT_CLIENT_ID: MQTT client identifier
• DEFAULT_ROBOT_ID: fallback robot id when a tool omits robot_id
• REQUEST_TIMEOUT_MS: default timeout for MQTT request-response operations
• RMS_HOST, RMS_PORT, RMS_MCP_PATH: MCP WebSocket bind settings
• RCS_MCP_SERVER_URL: convenience value for the RCS-side MCP configuration

LLM bridge values:

• LLM_BRIDGE_PROVIDER=ollama
• LLM_BRIDGE_URL=http://127.0.0.1:11434/api/chat
• LLM_BRIDGE_MODEL=qwen3
• LLM_BRIDGE_TIMEOUT_MS=30000
• LLM_BRIDGE_THINK= optional
• LLM_BRIDGE_KEEP_ALIVE=5m

Recommended local setup:

1. Install Ollama
2. Pull a model with tool-calling support such as qwen3
3. Start Ollama
4. Keep LLM_BRIDGE_URL=http://127.0.0.1:11434/api/chat

Windows 11 Ollama Setup

1. Download the Windows installer from the official site: https://ollama.com/download/windows
2. Run the installer and finish the setup
3. Open a new PowerShell window and confirm installation:

ollama --version

4. Pull a model with tool-calling support:

ollama pull qwen3

5. Check available models:

ollama list

6. Start the local Ollama server if it is not already running:

ollama serve

7. In another terminal, start the full local stack:

npm run dev:all

MQTT Topics

Topics are resolved from symbolic keys. For example:

resolveTopic("navigation.command", { robot_id: "burger1" });
// => /amr/burger1/navigation/command

Example resolved topics:

• /amr/burger1/navigation/command
• /amr/burger1/navigation/result
• /amr/burger1/pose/set
• /amr/burger1/route/request
• /amr/burger1/system/ping

MCP Tools

The server exposes these high-level tools:

• chat
• navigate_to_poses
• cancel_navigation
• set_initial_pose
• save_map
• send_motion_command
• request_plan_segment
• request_plan_route
• ping_robot
• change_robot_id

Each request automatically includes request_id and timestamp, and request-response tools subscribe to the matching response topic and correlate by request_id.

chat Tool

chat is the main entry point for RCS natural-language interaction.

Expected behavior:

• RCS sends the latest operator utterance to the chat tool
• ros-mcp-server sends the conversation to Ollama
• Ollama requests robot tools when needed
• ros-mcp-server executes the requested tools
• the final Korean response is returned to RCS

Typical arguments:

{
  "message": "burger1을 map 기준 x=1.25, y=0.4 위치로 보내줘",
  "robot_id": "burger1"
}

Example MCP Tool Calls

After connecting your MCP client to ws://127.0.0.1:3001/mcp and completing MCP initialization, you can call tools like this.

chat:

{
  "jsonrpc": "2.0",
  "id": 9,
  "method": "tools/call",
  "params": {
    "name": "chat",
    "arguments": {
      "message": "burger1을 map 기준 x=1.25, y=0.4 위치로 보내줘",
      "robot_id": "burger1"
    }
  }
}

navigate_to_poses:

{
  "jsonrpc": "2.0",
  "id": 10,
  "method": "tools/call",
  "params": {
    "name": "navigate_to_poses",
    "arguments": {
      "robot_id": "burger1",
      "poses": [
        {
          "frame_id": "map",
          "position": { "x": 1.25, "y": 0.4, "z": 0 },
          "orientation": { "x": 0, "y": 0, "z": 0, "w": 1 }
        }
      ]
    }
  }
}

RCS Integration

RCS should connect its MCP client transport to:

ws://127.0.0.1:3001/mcp

Recommended client behavior:

• keep the current chat-style UI
• let the operator choose the UI label such as ChatGPT or Claude if desired
• send the operator message to MCP chat
• show the returned Korean response in the same chat thread
• avoid direct OpenAI API handling in the UI when using the RMS-side Ollama bridge

This keeps RCS thin while ros-mcp-server owns natural-language orchestration and robot tool execution.