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 \
git2.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 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-client5.2为什么需要这些包
fastmcp：MCP服务器框架pillow：图像处理numpy,scipy,matplotlib,pandas：过滤/分析实用程序opencv-python：必填，因为utils/websocket_manager.py导入cv2websocket-client：必填，因为utils/websocket_manager.py导入websocket
5.3验证导入
安装后运行此检查：
cd ~/nrs_llm
source env_llm/bin/activate
python - /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 -yGemini CLI内部：
/mcp list预期结果：
ros-mcp出现- 状态为
Ready - 列出了MCP工具
______________________________________________________________________
17.快速命令摘要
一次性设置
cd ~
git clone 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-clientROS工作空间构建
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.xmlGemini 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 国家。