dsr_mcp_server

DSR MCP 服务

一个 MCP（Model Context Protocol）服务，提供一套全面的工具，用于查询、操作和分析深度状态表示（DSR）图。此服务通过标准化的 MCP 工具、实时图操作和智能节点关系管理，让 AI 助手能够与机器人感知和场景理解数据交互。

工具

工具名称	描述	参数
check_dsr_connection	检查 DSR 连接并返回状态信息	—
get_all_nodes	获取 DSR 图中的所有节点	—
get_nodes_by_type	按节点类型筛选节点（例如，机器人、人员、房间）	node_type: str
get_node_details	获取特定节点的详细信息，包括属性和边	node_identifier: str
get_all_edges	获取 DSR 图中的所有边	—
insert_node	在 DSR 图中插入新节点	name: str, node_type: str
insert_edge	在 DSR 图中的两个节点之间插入新边	origin_id: str, destination_id: str, edge_type: str
insert_edge_attribute	在 DSR 图中插入或更新边的属性	origin_id: str, destination_id: str, attribute_name: str, attribute_value: str, attribute_type: str = 'string'
update_node	在 DSR 图中使用新属性更新节点	node_id: str, attribute_name: str, attribute_value: str, attribute_type: str = 'string'
delete_node	从 DSR 图中删除节点	node_id: str
delete_edge	从 DSR 图中删除边	origin_id: str, destination_id: str, edge_type: str
save_graph	将 DSR 图的当前状态保存到 JSON 文件	交互式文件路径选择

资源

资源提供对 DSR 图数据的只读、高效访问，非常适合在不修改图状态的情况下查询信息。

资源 URI	描述	返回内容
dsr://nodes	DSR 图中的所有节点及其基本信息	包含节点数组、数量和 DSR 名称的 JSON
dsr://nodes/type/{type}	按类型筛选的节点及其完整详情（属性、边）	包含详细节点数组、数量和类型的 JSON
dsr://nodes/{node_id}	特定节点的详细信息	包含节点详情、属性和关联边的 JSON
dsr://edges	DSR 图中的所有边	包含边数组、数量和 DSR 名称的 JSON

环境变量

变量	默认值	描述
DSR_AGENT_ID	42	DSR 连接的唯一 Agent 标识符
DSR_NAME	mcp_server	要连接的目标 DSR 图名称
SERVER_HOST	127.0.0.1	服务主机地址
SERVER_PORT	3000	服务端口号

安装

依赖项

• fastmcp：MCP 服务框架（>= 2.2.7）
• Cortex：用于图操作的 DSR 库
• Python：需要 3.12+

注意： 必须在虚拟环境中构建 Cortex，以确保兼容性。

cd dsr_mcp_server
source .venv/bin/activate
cd ${CORTEX_DIR} && make -p build && cd build
cmake .. && make -j$(nproc) && sudo make install

使用 uv 安装（推荐）

克隆仓库并使用 uv 安装：

git clone https://github.com/grupo-avispa/dsr_mcp_server.git
cd dsr_mcp_server
uv sync

或者直接从仓库安装：

uv add git+https://github.com/grupo-avispa/dsr_mcp_server.git

使用 pip 安装

以模式安装软件包：

git clone https://github.com/grupo-avispa/dsr_mcp_server.git
cd dsr_mcp_server
python3 -m pip install .

或者直接从仓库安装：

python3 -m pip install git+https://github.com/grupo-avispa/dsr_mcp_server.git

使用方法

使用 uv 运行

uv run dsr_mcp_server

使用 pip 安装后运行

python3 -m dsr_mcp_server

服务将启动，并尝试使用已配置的参数自动初始化 DSR 连接。

Claude Desktop/Cursor/VSCode 的配置示例

使用 uv（推荐）

将此配置添加到应用的设置中（mcp.json）：

{
  "dsr mcp server": {
    "type": "stdio",
    "command": "uv",
    "args": [
      "run",
      "--directory",
      "/path/to/dsr_mcp_server",
      "dsr_mcp_server"
    ],
    "env": {
      "DSR_AGENT_ID": "42",
      "DSR_NAME": "your_dsr_graph_name"
    }
  }
}

使用 pip 安装

{
  "dsr mcp server": {
    "type": "stdio",
    "command": "python3",
    "args": [
      "-m",
      "dsr_mcp_server"
    ],
    "env": {
      "DSR_AGENT_ID": "42", 
      "DSR_NAME": "your_dsr_graph_name"
    }
  }
}

HTTP 服务模式

用于 HTTP 传输集成：

{
  "servers": {
    "dsr_mcp_server": {
      "type": "http",
      "url": "http://localhost:3000/mcp"
    }
  }
}

技术说明

• DSR 连接会自动初始化并监控连接状态。
• 节点属性会经过筛选，排除内部渲染属性（color、depth、height、level 等），以使输出更简洁。
• 边关系支持多种类型，包括空间关系（near）、所有权关系（has）、身份关系（is）和关联关系（is_with）语义。
• 图操作通过 DSR 库内置的验证机制确保一致性。
• 所有工具都会返回标准化的 JSON 响应，其中包含成功/错误状态和详细信息。
• 通过 MCP 的 elicit 机制交互式选择图导出操作所用的文件。
• 资源以只读、幂等的方式访问 DSR 图数据，支持高效缓存，且与工具相比开销更低。查询数据时使用资源，修改数据时使用工具。

贡献

1. Fork 仓库
2. 创建功能分支
3. 按照编码规范进行修改
4. 视情况添加测试
5. 提交拉取请求

支持

如有问题、疑问或想要贡献，请参阅项目的问题跟踪器，或联系开发团队。