使用说明

nrs_llm

nrs_llm 是用于ROS 2环境的MCP服务器。它通过以下方式连接到ROS rosbridge WebSocket 并公开了以下工具：

ROS 2主题/服务反思
主题发布/订阅工作流
服务调用
机器人连接检查
抛光原木的过滤与分析
抛光路径再生
基于TXT的抛光路径执行和记录

此存储库是围绕以下环境假设设计的：

Ubuntu 22.04
ROS 2谦逊
Python 3.10+
单独的ROS 2工作区位于 ~/ros2_ws
rosbridge_server 运行于 127.0.0.1:9090

编写此README是为了让用户可以设置和运行 nrs_llm 从头开始。

1.推荐的目录布局

保持以下布局时，当前代码库最容易运行：

~/nrs_llm
~/ros2_ws
├── src
│   └── ... your ROS 2 packages
├── build
├── install
├── log
└── data
    └── ep
        ├── xyz.txt
        ├── vxyz.txt
        ├── fxyz.txt
        ├── rpy.txt
        ├── real_flat_filtered.txt
        ├── auto_logger.py
        ├── filter_logs_txt.py
        ├── polish_pipeline.py
        └── ...

如果移动这些路径，抛光管道的某些部分可能会失败，除非您在代码中更新相应的路径。

2.系统要求

首先安装基础系统工具。

2.1 Ubuntu软件包

sudo apt update
sudo apt install -y \
    python3 \
    python3-pip \
    python3-venv \
    python3-colcon-common-extensions \
    git

2.2 ROS 2谦逊

本README假定 ROS 2 Humble已安装 在：

/opt/ros/humble

请检查：

test -f /opt/ros/humble/setup.bash && echo "ROS 2 Humble found" || echo "ROS 2 Humble missing"

如果这打印出来 ROS 2 Humble missing，请先安装ROS 2 Humble，然后再继续。

3.克隆存储库

将此存储库克隆到您的主目录中：

cd ~
git clone <YOUR_REPOSITORY_URL> nrs_llm
cd ~/nrs_llm

如果存储库已经克隆，只需移动到其中：

cd ~/nrs_llm

4.创建并激活Python虚拟环境

此项目应在专用虚拟环境中运行。

创造环境：

cd ~/nrs_llm
python3 -m venv env_llm

激活它：

source ~/nrs_llm/env_llm/bin/activate

激活后，您的终端提示应显示如下内容：

(env_llm) user@host:~/nrs_llm$

升级pip：

python -m pip install --upgrade pip

稍后停用：

deactivate

要在新终端中再次激活：

cd ~/nrs_llm
source env_llm/bin/activate

5.安装Python依赖项

在内部安装所需的Python包 env_llm.

5.1核心包

cd ~/nrs_llm
source env_llm/bin/activate

pip install \
    fastmcp \
    pillow \
    numpy \
    scipy \
    matplotlib \
    pandas \
    opencv-python \
    websocket-client

5.2为什么需要这些包

fastmcp：MCP服务器框架
pillow：图像处理
numpy, scipy, matplotlib, pandas：过滤/分析实用程序
opencv-python：必填，因为 utils/websocket_manager.py 导入 cv2
websocket-client：必填，因为 utils/websocket_manager.py 导入 websocket

5.3验证导入

安装后运行此检查：

cd ~/nrs_llm
source env_llm/bin/activate
python - <<'PY'
import cv2
import websocket
import numpy
import pandas
import scipy
import matplotlib
from PIL import Image
print("All required Python imports succeeded.")
PY

如果此命令成功，则Python环境已准备就绪。

6.准备ROS 2工作区

本项目假设ROS 2工作区位于 ~/ros2_ws.

如果需要，创建它：

mkdir -p ~/ros2_ws/src

将您所需的ROS 2包放入 ~/ros2_ws/src.

当前版本假定工作区包括机器人设置和抛光执行管道所需的包。在先前版本中， ur_custom_ik 以及可执行文件 txt_ik_executor_force_patched 被路径执行流使用。

7.构建ROS 2工作区

构建工作空间：

cd ~/ros2_ws
colcon build

环境来源：

source /opt/ros/humble/setup.bash
source ~/ros2_ws/install/setup.bash

要确认工作区源文件存在，请执行以下操作：

test -f ~/ros2_ws/install/setup.bash && echo "ROS workspace found" || echo "ROS workspace missing"

如果文件丢失，则表示工作区尚未成功构建。

8.安装并运行罗斯布里奇

nrs_llm 做不直接与ROS 2对话。它通过以下方式进行通信 rosbridge WebSocket.

8.1必要时安装罗斯布里奇

如果 rosbridge_server 尚未安装：

sudo apt update
sudo apt install -y ros-humble-rosbridge-server

8.2运行罗斯布里奇

打开一个新终端并运行：

source /opt/ros/humble/setup.bash
source ~/ros2_ws/install/setup.bash
ros2 launch rosbridge_server rosbridge_websocket_launch.xml

默认情况下，rosbridge会监听：

127.0.0.1:9090

8.3验证罗斯布里奇是否在监听

在另一个终端中：

ss -ltnp | grep 9090

如果rosbridge运行正常，您应该在端口上看到一个侦听器 9090.

9.验证存储库结构

连接前 nrs_llm 在Gemini CLI中，确认这些文件存在：

test -f ~/nrs_llm/server.py && echo "server.py found" || echo "server.py missing"
test -f ~/ros2_ws/install/setup.bash && echo "workspace setup found" || echo "workspace setup missing"
test -f /opt/ros/humble/setup.bash && echo "ROS Humble setup found" || echo "ROS Humble setup missing"
test -x ~/nrs_llm/env_llm/bin/python && echo "venv python found" || echo "venv python missing"

所有四项检查都应该成功。

10.在中配置Gemini CLI MCP `settings.json`

nrs_llm 计划于 Gemini CLI 作为MCP服务器，使用标准.

这意味着：

做不手动保存 python server.py 在另一个终端中运行
Gemini CLI应自行启动服务器
在启动之前，配置应该为两个ROS环境提供源代码 server.py

10.1编辑Gemini CLI `settings.json`

打开 相同 settings.json Gemini CLI已在读取MCP配置的文件 并添加以下服务器条目：

{
  "mcpServers": {
    "ros-mcp": {
      "command": "/bin/bash",
      "args": [
        "-lc",
        "source /opt/ros/humble/setup.bash && source /home/eunseop/ros2_ws/install/setup.bash && cd /home/eunseop/nrs_llm && exec /home/eunseop/nrs_llm/env_llm/bin/python /home/eunseop/nrs_llm/server.py"
      ]
    }
  }
}

10.2关于此配置的重要注意事项

如果您的用户名或目录不同，请替换路径。

对于上面显示的当前设置：

ROS 2 Humble源文件： /opt/ros/humble/setup.bash
ROS工作区源文件： /home/eunseop/ros2_ws/install/setup.bash
存储库路径： /home/eunseop/nrs_llm
虚拟环境Python： /home/eunseop/nrs_llm/env_llm/bin/python

10.3为什么 `/bin/bash -lc` 被使用

这很重要，因为它允许Gemini CLI：

来源ROS 2 Humble
获取您的ROS 2工作区
将目录更改为存储库
运行正确的虚拟环境Python

如果没有这个，服务器可能会因缺少ROS包、缺少Python模块或相对路径中断而失败。

11.启动Gemini CLI并验证MCP服务器

曾经 settings.json 更新后，从存储库环境中启动Gemini CLI：

cd ~/nrs_llm
source env_llm/bin/activate
gemini -y

在Gemini CLI中，运行：

/mcp list

如果一切正常，你应该看看 ros-mcp 在列表中，状态类似于：

Ready

如果服务器连接正确，Gemini CLI还应显示可用工具的列表。

12.连接后的首次推荐检查

曾经 /mcp list 显示 ros-mcp 准备就绪后，按以下顺序测试服务器：

connect_to_robot
get_topics
get_services
get_topic_type
get_service_type
publish_once 或只读自省工具

这有助于区分：

MCP启动问题
罗斯布里奇连接问题
ROS图可见性问题
机器人特定的执行问题

13.手动运行服务器进行调试

即使Gemini CLI应该在正常使用中启动MCP服务器，手动执行对于调试仍然有用。

13.1手动调试运行

cd ~/nrs_llm
source env_llm/bin/activate
source /opt/ros/humble/setup.bash
source ~/ros2_ws/install/setup.bash
python ~/nrs_llm/server.py

13.2使用stdout/stderr分离进行更好的调试检查

timeout 5s /bin/bash -lc 'source /opt/ros/humble/setup.bash && source /home/eunseop/ros2_ws/install/setup.bash && cd /home/eunseop/nrs_llm && /home/eunseop/nrs_llm/env_llm/bin/python /home/eunseop/nrs_llm/server.py' >/tmp/ros_mcp_stdout.log 2>/tmp/ros_mcp_stderr.log

echo "===== STDOUT ====="
sed -n '1,80p' /tmp/ros_mcp_stdout.log
echo "===== STDERR ====="
sed -n '1,80p' /tmp/ros_mcp_stderr.log

这对于捕获丢失等导入错误非常有用 cv2 或失踪 websocket 支持。

14.抛光管道使用的默认路径

当前代码库采用以下默认路径进行过滤/分析/再生/执行：

过滤输入

~/ros2_ws/data/ep/xyz.txt
~/ros2_ws/data/ep/vxyz.txt
~/ros2_ws/data/ep/fxyz.txt
~/ros2_ws/data/ep/rpy.txt

分析输入/输出

~/ros2_ws/data/ep/vxyz_filtered.txt
~/ros2_ws/data/ep/fxyz_filtered.txt
输出目录： ~/ros2_ws/data/ep/polish_out_filtered

再生

输入路径： ~/ros2_ws/data/ep/real_flat_filtered.txt
删除映射： ~/ros2_ws/data/ep/polish_out_filtered/removal_map.npz
输出路径： ~/ros2_ws/data/ep/real_flat_filtered_new2.txt

路径执行

记录器： ~/ros2_ws/data/ep/auto_logger.py
执行人： ros2 run ur_custom_ik txt_ik_executor_force_patched

如果缺少这些文件或目录中的任何一个，相应的管道阶段可能会失败。

15.常见错误和修复

15.1 `ModuleNotFoundError: No module named 'cv2'`

原因：

opencv-python 未安装在 env_llm

修复：

cd ~/nrs_llm
source env_llm/bin/activate
pip install opencv-python

15.2 `ModuleNotFoundError: No module named 'websocket'`

原因：

websocket-client 未安装在 env_llm

修复：

cd ~/nrs_llm
source env_llm/bin/activate
pip install websocket-client

注意：导入名称为 websocket，但您安装的软件包是 websocket-client.

15.3 `/mcp list` 显示 `Disconnected`

常见原因：

Gemini CLI未读取 settings.json 您编辑的文件
MCP服务器命令错误
ROS环境没有来源
虚拟环境Python路径错误
server.py 启动时因缺少依赖项而崩溃
罗斯布里奇没有运行

检查表：

test -x /home/eunseop/nrs_llm/env_llm/bin/python && echo OK
test -f /home/eunseop/nrs_llm/server.py && echo OK
test -f /opt/ros/humble/setup.bash && echo OK
test -f /home/eunseop/ros2_ws/install/setup.bash && echo OK

然后验证罗斯布里奇：

ss -ltnp | grep 9090

然后运行第13.2节中的5秒调试命令。

15.4 `No executable found`

原因：

未构建所需的ROS包
工作区未来源
可执行文件名与代码所期望的不同

修复：

cd ~/ros2_ws
colcon build
source /opt/ros/humble/setup.bash
source ~/ros2_ws/install/setup.bash
ros2 pkg executables ur_custom_ik

15.5 `No such file or directory`

原因：

缺少文件 ~/ros2_ws/data/ep
缺少抛光脚本
代码中的错误路径假设

修复：

ls ~/ros2_ws/data/ep

检查所有必需的TXT文件和脚本是否确实存在。

15.6 pip警告不相关的包，例如 `nrs-imitation`

如果您的虚拟环境意外包含无关的可编辑安装， pip 可能会显示与以下内容没有直接关系的依赖性警告 nrs_llm.

检查：

pip show nrs-imitation

如果你不想把包裹放进去 env_llm，将其删除：

pip uninstall -y nrs-imitation

16.完整的启动顺序（推荐）

每次使用以下顺序。

1号航站楼：罗斯布里奇

source /opt/ros/humble/setup.bash
source ~/ros2_ws/install/setup.bash
ros2 launch rosbridge_server rosbridge_websocket_launch.xml

终端2：Gemini CLI

cd ~/nrs_llm
source env_llm/bin/activate
gemini -y

Gemini CLI内部：

/mcp list

预期结果：

ros-mcp 出现
状态为 Ready
列出了MCP工具

17.快速命令摘要

一次性设置

cd ~
git clone <YOUR_REPOSITORY_URL> nrs_llm
cd ~/nrs_llm
python3 -m venv env_llm
source env_llm/bin/activate
python -m pip install --upgrade pip
pip install fastmcp pillow numpy scipy matplotlib pandas opencv-python websocket-client

ROS工作空间构建

mkdir -p ~/ros2_ws/src
cd ~/ros2_ws
colcon build

罗斯布里奇跑道

source /opt/ros/humble/setup.bash
source ~/ros2_ws/install/setup.bash
ros2 launch rosbridge_server rosbridge_websocket_launch.xml

Gemini CLI运行

cd ~/nrs_llm
source env_llm/bin/activate
gemini -y

18.总结

跑 nrs_llm 如果成功，您需要以下所有条件：

ROS 2 Humble已安装
一个内置的ROS 2工作空间 ~/ros2_ws
罗斯布里奇在港口行驶 9090
克隆的存储库位于 ~/nrs_llm
这 env_llm 创建并激活虚拟环境
已安装所有必需的Python依赖项
Gemini CLI settings.json 配置为启动 server.py 通过 /bin/bash -lc

如果您完全遵循此README，您应该能够启动Gemini CLI，运行 /mcp list，并查看 ros-mcp 在 Ready 国家。