resq-software/mcp
GitHub: resq-software/mcp
将 ResQ 应急响应平台的数字孪生仿真、无人机协调和事件处置能力通过 MCP 协议暴露给 AI 客户端的桥接服务器。
Stars: 0 | Forks: 0
# resQ MCP Server
**resQ MCP** 仓库提供了 [Model Context Protocol](https://modelcontextprotocol.io/) 的生产就绪实现，将 [ResQ 平台](https://resq.software)的核心功能——Digital Twin Simulations (DTSOP)、Hybrid Coordination Engines (HCE) 和无人机遥测——直接连接到 Claude Desktop、Cursor 和 MCP Inspector 等 AI 驱动的环境中。
## 目录
- [概述](#overview)
- [功能特性](#features)
- [架构](#architecture)
- [快速开始](#quick-start)
- [使用方法](#usage)
- [配置](#configuration)
- [API 概览](#api-overview)
- [开发](#development)
- [贡献](#contributing)
- [路线图](#roadmap)
- [许可证](#license)
## 概述
`resq-mcp` 基于 [FastMCP](https://github.com/jlowin/fastmcp) 构建，能够将复杂的机器人和仿真工作流快速集成到 LLM 中。它充当您的 AI agent 和 ResQ 后端之间的安全中介。
### 核心模块
* **DTSOP**: 管理数字孪生仿真生命周期。
* **HCE**: 协调跨异构资产的混合操作。
* **PDIE**: 处理平台定义的事件评估。
* **Telemetry**: 无人机状态的实时流式传输和监控。
## 功能特性
* **双向传输**: 支持 `STDIO` 用于本地集成，支持 `SSE` 用于远程基础设施。
* **强类型**: 对所有工具输入和资源输出进行完整的 Pydantic 验证。
* **安全第一**: 可配置的 `SAFE_MODE` 以防止破坏性操作。
* **事件驱动**: 支持长时间运行仿真的异步通知。
* **开箱即用的 Prompts**: 包含内置的事件响应和分析模板。
## 架构
该系统利用模块化的 Python 后端，包含结构化的领域对象和标准化的通信协议。
```
graph TD
User[AI Client / Claude] <-->|MCP Protocol| Server[resq-mcp Server]
Server -->|Validation| Config[Config / Pydantic]
Server -->|Internal API| Core[ResQ Platform API]
Core --> DTSOP[DTSOP Engine]
Core --> HCE[Hybrid Coordination Engine]
Core --> Telemetry[Drone Telemetry]
```
## 快速开始
### 1. 前置条件
确保您已安装 [uv](https://github.com/astral-sh/uv)。
### 2. 安装
```
# 安装 package
uv add resq-mcp
# 或从 source 克隆
git clone https://github.com/resq-software/mcp.git
cd mcp && uv sync
```
### 3. 执行
**标准模式 (STDIO):**
```
uv run resq-mcp
```
**网络模式 (SSE):**
```
RESQ_HOST=0.0.0.0 RESQ_PORT=8000 uv run resq-mcp
```
## 使用方法
### 连接到 Claude Desktop
将以下内容添加到您的 `~/Library/Application Support/Claude/claude_desktop_config.json`：
```
{
"mcpServers": {
"resq": {
"command": "uv",
"args": ["run", "resq-mcp"],
"env": { "RESQ_API_KEY": "your-prod-token" }
}
}
}
```
### 工具调用示例
触发事件仿真：
```
# 通过 AI Interface
# Tool: trigger_simulation
# Payload: { "incident_type": "wildfire", "location": {"lat": 37.7, "lon": -122.4} }
```
### 资源订阅
访问实时数据：
```
resq://drones/active
```
## 配置
设置通过环境变量管理，并由 `src/resq_mcp/config.py` 进行验证。
| Variable | Description | Default |
| :--- | :--- | :--- |
| `RESQ_API_KEY` | 认证 token | `resq-dev-token` |
| `RESQ_SAFE_MODE` | 如果为 true，阻止变更工具 | `true` |
| `RESQ_DEBUG` | 详细日志记录 | `false` |
| `RESQ_PORT` | SSE 服务器端口 | `8000` |
## API 概览
服务器暴露了几个高级端点：
* **`trigger_simulation`**: 启动新的 DTSOP 仿真实例。
* **`get_drone_telemetry`**: 轮询活动无人机状态或订阅事件。
* **`validate_incident`**: 根据 PDIE 协议运行检查以评估威胁等级。
* **`list_strategies`**: 获取正在发生的事件的缓存部署策略。
有关详细的参数定义，请参阅 `src/resq_mcp/tools.py`。
## 开发
该项目包含 pre-commit hooks 和 CI/CD 流水线以确保代码健康。
### 设置
```
./scripts/setup.sh
```
### 测试
我们使用 `pytest` 并配合大量的外部 ResQ API mock 进行测试。
```
uv run pytest tests/
```
### 类型检查
```
uv run mypy src/
```
## 贡献
1. **Fork** 本仓库。
2. **Feature Branch**: 创建一个分支，遵循 `feat/`、`fix/` 或 `refactor/` 前缀。
3. **Commit Convention**: 遵循 [Conventional Commits](https://www.conventionalcommits.org/)。
4. **Pull Request**: 确保 CI 通过（测试、linting 和覆盖率）。
查看 `CONTRIBUTING.md` 了解完整的编码标准。
## 路线图
- [ ] 支持 OAuth2 认证流程。
- [ ] 扩展的遥测可视化资源。
- [ ] 用于高频更新的实时 WebSocket 支持。
- [ ] 用于第三方协调引擎的插件架构。
## 许可证
Copyright 2026 ResQ. 根据 Apache License, Version 2.0 分发。有关详细信息，请参阅 [LICENSE](./LICENSE)。
标签：AI代理集成, AI接口, Claude Desktop, Cursor, DTSOP, FastMCP, HCE, LLM集成, MCP服务器, Model Context Protocol, PDIE, Pydantic验证, Python, ResQ平台, SSE传输, STDIO传输, 事件驱动架构, 事故处理, 大语言模型工具, 安全中间件, 库, 应急响应, 应急管理系统, 数字孪生, 无人机协调, 无人机遥测, 无后门, 机器人技术, 机器人流程自动化, 模拟仿真, 逆向工具