内容
# PlanSys2 MCP 服务器
[](https://github.com/ajtudela/plansys2_mcp_server/actions/workflows/python-package.yml)
[](https://github.com/ajtudela/plansys2_mcp_server/actions/workflows/docker_image.yml)
[](https://codecov.io/gh/ajtudela/plansys2_mcp_server)
一个 MCP（模型上下文协议）服务器，提供与 PlanSys2 自动规划系统交互的工具和资源，允许 AI 代理访问 PDDL 领域知识，管理规划问题，生成计划，并监控执行。
## 功能
* **领域管理**：访问 PDDL 领域定义、类型、谓词和动作。
* **问题定义**：查询和修改规划问题，包括实例和目标。
* **计划生成**：使用 PDDL 规划器生成计划。
* **执行监控**：监控计划执行并跟踪进度。
* **ROS 2 集成**：与 PlanSys2 和 ROS 2 生态系统完全兼容。
## 工具
### 领域专家工具
| 工具 | 描述 | 参数 |
| --- | --- | --- |
| **获取领域** | 获取完整的 PDDL 领域定义 | — |
| **获取领域动作** | 获取所有动作（常规和持续）及其详细信息，包括参数和前提条件 | — |
| **获取领域动作详情** | 获取特定动作的详细信息，包括参数、的前提条件和效果 | `名称：字符串` |
| **获取领域持续动作详情** | 获取特定持续动作的详细信息，包括参数和条件 | `名称：字符串` |
| **获取领域常量** | 获取特定类型的常量实例 | `类型名称：字符串` |
| **获取领域函数** | 获取领域中定义的所有函数及其参数 | — |
| **获取领域函数详情** | 获取特定函数的详细信息，包括其完整结构 | `名称：字符串` |
| **获取领域谓词** | 获取所有谓词和派生谓词及其详细信息和参数 | — |
| **获取领域谓词详情** | 获取特定谓词的详细信息，包括其完整结构 | `名称：字符串` |
| **获取领域派生谓词详情** | 获取特定派生谓词的详细信息，包括参数和派生规则 | `名称：字符串` |
| **获取领域类型** | 列出领域中定义的所有类型 | — |
### 问题专家工具
| 工具 | 描述 | 参数 |
| --- | --- | --- |
| **添加问题** | 添加完整的 PDDL 问题定义 | `问题：字符串` |
| **添加问题函数** | 向问题添加函数及其值 | `函数：字符串` |
| **添加问题目标** | 添加或设置问题的目标规范 | `目标：字符串` |
| **添加问题实例** | 向问题添加新的对象实例 | `名称：字符串，实例类型：字符串` |
| **添加问题谓词** | 向当前状态添加谓词 | `谓词：字符串` |
| **清除问题知识** | 重置所有问题数据（实例、谓词和目标） | — |
| **检查问题函数** | 检查问题中是否存在函数 | `函数：字符串` |
| **检查问题谓词** | 检查问题中是否存在谓词 | `谓词：字符串` |
| **获取问题** | 获取完整的 PDDL 问题定义 | — |
| **获取问题函数** | 获取问题中所有函数及其名称和类型 | — |
| **获取问题函数详情** | 获取特定函数的详细信息，包括值 | `函数：字符串` |
| **获取问题目标** | 获取当前问题目标 | — |
| **获取问题实例** | 获取所有对象实例及其名称和类型 | — |
| **获取问题实例详情** | 获取特定实例的详细信息 | `名称：字符串` |
| **获取问题谓词** | 获取当前状态的所有谓词 | — |
| **获取问题谓词详情** | 获取特定谓词的详细信息 | `谓词：字符串` |
| **检查问题目标是否满足** | 检查目标在当前状态是否满足 | `目标：字符串` |
| **删除问题函数** | 从当前状态删除函数 | `函数：字符串` |
| **删除问题目标** | 从问题中删除当前目标 | — |
| **删除问题实例** | 从问题中删除对象实例 | `名称：字符串` |
| **删除问题谓词** | 从当前状态删除谓词 | `谓词：字符串` |
| **更新问题函数** | 更新问题中的函数值 | `函数：字符串` |
### 计划器工具
| 工具 | 描述 | 参数 |
| --- | --- | --- |
| **生成计划** | 为给定的 PDDL 领域和问题生成计划 | `领域：字符串，问题：字符串` |
| **验证领域** | 验证 PDDL 领域定义 | `领域：字符串` |
### 执行器工具
| 工具 | 描述 | 参数 |
| --- | --- | --- |
| **执行计划** | 执行计划 | `计划：字符串` |
| **获取当前计划** | 获取当前正在执行的计划 | — |
| **获取剩余计划** | 获取计划中剩余的动作 | — |
## 资源
服务器提供三个 MCP 资源：
- `plansys2://domain` - 当前 PDDL 领域
- `plansys2://problem` - 当前 PDDL 问题
- `plansys2://plan` - 当前正在执行的计划
## 配置
### 环境变量
| 变量 | 默认值 | 描述 |
| --- | --- | --- |
| `TRANSPORT_MODE` | `stdio` | 传输模式：`stdio`（本地集成）或 `http`（网络） |
| `HTTP_HOST` | `0.0.0.0` | HTTP 主机绑定（仅在 `TRANSPORT_MODE=http` 时使用） |
| `HTTP_PORT` | `3001` | HTTP 端口（仅在 `TRANSPORT_MODE=http` 时使用） |
| `LOG_LEVEL` | `INFO` | 日志级别：`DEBUG`、`INFO`、`WARNING`、`ERROR`、`CRITICAL` |
| `ROS_DOMAIN_ID` | — | ROS 2 网络隔离的域名 ID（推荐） |
| `ROS_LOCALHOST_ONLY` | — | 设置为 `1` 以限制 ROS 2 通信仅限 localhost |
### 安装
1. 复制环境配置模板：
```bash
cp .env.example .env
```
2. 编辑 `.env` 以自定义设置：
```bash
# 传输模式：'stdio' 用于本地，'http' 用于容器化/网络
TRANSPORT_MODE=stdio
# HTTP 设置（仅在 http 传输模式下需要）
HTTP_HOST=0.0.0.0
HTTP_PORT=3001
# 日志记录
LOG_LEVEL=INFO
```
## 安装
### 依赖项
- [机器人操作系统（ROS）2](https://docs.ros.org/en/jazzy/)：机器人中间件（Jazzy）
- [PlanSys2](https://github.com/PlanSys2/ros2_planning_system)：自动规划框架
- [fastmcp](https://github.com/jlowin/fastmcp)：MCP 服务器框架
### 使用 uv 安装（推荐）
克隆仓库并使用 uv 安装：
```bash
git clone https://github.com/ajtudela/plansys2_mcp_server.git
cd plansys2_mcp_server
# 如有需要，设置 ROS 2 环境变量
export ROS_DOMAIN_ID=0
uv sync
```
或直接从仓库安装：
```bash
uv add git+https://github.com/ajtudela/plansys2_mcp_server.git
```
### Docker
#### 构建镜像
构建镜像：
```bash
docker build -t plansys2_mcp_server:latest .
```
#### 拉取镜像
从 Docker 仓库拉取最新镜像：
```bash
docker pull ghcr.io/ajtudela/plansys2_mcp_server:latest
```
## 用法
### 使用 uv 运行
```bash
uv run plansys2-mcp-server
```
### 在 HTTP 模式下运行
```bash
TRANSPORT_MODE=http HTTP_HOST=0.0.0.0 HTTP_PORT=3001 uv run plansys2-mcp-server
```
### 配置示例适用于 Claude Desktop/Cursor/VSCode
将此配置添加到应用程序设置（mcp.json）：
#### 使用 uv（stdio 传输）
```json
{
"plansys2 mcp server": {
"type": "stdio",
"command": "uv",
"args": [
"run",
"--directory",
"/path/to/plansys2_mcp_server",
"plansys2-mcp-server"
],
"env": {
"ROS_DOMAIN_ID": "0",
"ROS_LOCALHOST_ONLY": "1",
"TRANSPORT_MODE": "stdio",
"LOG_LEVEL": "INFO"
}
}
}
```
#### 使用 Docker（stdio 传输）
```json
"plansys2 mcp server": {
"type": "stdio",
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"ghcr.io/ajtudela/plansys2_mcp_server"
],
"env": {
"ROS_DOMAIN_ID": "0",
"ROS_LOCALHOST_ONLY": "1",
"TRANSPORT_MODE": "stdio",
"LOG_LEVEL": "INFO"
}
}
```
#### 使用 HTTP 传输
```json
"plansys2 mcp server": {
"type": "http",
"url": "http://localhost:3001/mcp",
"env": {
"TRANSPORT_MODE": "http",
"LOG_LEVEL": "INFO"
}
}
```
