Content
# 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](/C:/ws/src/ros-mcp-server/rms_mqtt/protocols/amr-mqtt-protocol.json). MCP tools resolve symbolic keys such as `navigation.command` instead of hardcoding topic strings.
## Folder Structure
```text
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
```bash
npm install
```
## Run
```bash
npm run dev
```
To start both the RMS server and a local Ollama runtime together:
```bash
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:
```text
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:
```powershell
ollama --version
```
4. Pull a model with tool-calling support:
```powershell
ollama pull qwen3
```
5. Check available models:
```powershell
ollama list
```
6. Start the local Ollama server if it is not already running:
```powershell
ollama serve
```
7. In another terminal, start the full local stack:
```powershell
npm run dev:all
```
## MQTT Topics
Topics are resolved from symbolic keys. For example:
```ts
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:
```json
{
"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`:
```json
{
"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`:
```json
{
"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:
```text
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.
