无人机乘员MCP网关
宣言驱动的MCP网关，使UAVCrew的人工智能代理能够通过现有的REST API安全访问您的无人机操作数据。
概述
网关运行 您的基础设施 并将MCP工具调用转换为针对REST API的经过验证的HTTP请求。UAVCrew的AI代理使用HTTPS连接 模型上下文协议 读取、搜索数据并对其采取行动，而无需直接访问数据库。
┌─────────────────────────────────────────────────────────────────┐
│ YOUR INFRASTRUCTURE │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Your REST │ │ MCP Gateway │ │ HTTPS │ │
│ │ API (Django, │` |从UAVCrew添加API密钥|
| `uavcrew keys remove
` |删除API密钥|
| `uavcrew generate-systemd` |生成并安装systemd单元文件|
______________________________________________________________________
## 配置
### 环境变量
|变量|必填|默认|描述|
|----------|----------|---------|-------------|
| `MCP_JWT_PUBLIC_KEY_PATH` |是的| `keys/k3_public.pem` |用于验证T1 JWT的K3公钥路径|
| `CLIENT_API_BASE_URL` |否|来自清单| REST API的基本URL|
| `MCP_HOST` |没有| `127.0.0.1` |服务器绑定地址|
| `MCP_PORT` |没有| `8400` |服务器端口|
| `MCP_SERVER_NAME` |没有| `MCP Gateway` |UAVCrew仪表板的友好名称|
| `MCP_PUBLIC_URL` |无|--|UAVCrew连接的HTTPS URL|
| `CLIENT_API_TOKEN` |无|-|单租户静态模式的客户端API令牌（K4）|
| `LOG_LEVEL` |没有| `INFO` |日志级别：调试、信息、警告、错误|
看 [.env.示例](.env.example) 获取带有auth模式文档的完整模板。
### 清单
网关由 `manifest.json` 声明实体、API路径和可用操作的文件。看 [manifest.json.example](manifest.json.example) 对于完整的模式。
{ "api_base_url": "https://api.example.com/api/v1", "auth": { "mode": "dynamic", "resolver_path": "/internal/mcp/resolve-token" }, "entities": { "pilot": { "path": "/pilots", "id_field": "id", "read": true, "search": true, "actions": { "create": { "method": "POST", "path": "/pilots" }, "update": { "method": "PATCH", "path": "/pilots/{id}" } } } } }
### 身份验证模式
网关支持两种身份验证模式，配置如下 `manifest.json`:
**动态（推荐，多租户）：**
{ "auth": { "mode": "dynamic", "resolver_path": "/internal/mcp/resolve-token" } }
UAVCrew发送T1代表团JWT，并与RS256签署。网关使用K3公钥进行验证，并调用您的解析器端点以获得每个参与者的API令牌（K4）。集 `MCP_JWT_PUBLIC_KEY_PATH` 在 `.env`.
**静态（单租户）：**
{ "auth": { "mode": "static", "token_env": "CLIENT_API_TOKEN" } }
单个API令牌（K4）用于向您的客户端API发出的所有请求。集 `CLIENT_API_TOKEN` 在 `.env`UAVCrew通过T1 JWT（用K3验证）进行身份验证，与动态模式相同。
______________________________________________________________________
## MCP工具
网关向UAVCrew AI代理公开4个工具和1个资源：
|工具|说明|
|------|-------------|
| `get_entity` |按ID（或类似单例的公司）获取单个实体记录|
| `list_entities` |列出具有过滤、排序和分页功能的实体记录|
| `search` |在一个或所有实体类型中搜索|
| `action` |对实体执行写入操作（创建、更新、启动等）|
|资源|描述|
|----------|-------------|
| `entities://manifest` |实体定义、路径和可用操作|
______________________________________________________________________
## API终点
|方法|路径|身份验证|描述|
|--------|------|------|-------------|
| `GET` | `/health` |否|健康检查（版本、实体计数、身份验证模式）|
| `POST` | `/mcp` |承载|MCP可流式HTTP端点|
### 连接中
Health check
curl http://localhost:8400/health
MCP endpoint (use any MCP-compatible client)
mcp connect http://localhost:8400/mcp --header "Authorization: Bearer YOUR_KEY"
______________________________________________________________________
## HTTPS设置
网关监听本地端口。始终在其前面放置一个带有TLS的反向代理。
**Caddy（推荐--自动HTTPS）：**
mcp.yourcompany.com { reverse_proxy localhost:8400 }
**Nginx：**
server { server_name mcp.yourcompany.com; location / { proxy_pass http://127.0.0.1:8400; proxy_set_header Host $host; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } }
Then: sudo certbot --nginx -d mcp.yourcompany.com
安装向导(`uavcrew setup`)可以为您生成这些配置。
______________________________________________________________________
## 安全
1. **超文本传输安全协议** --始终使用TLS终止的反向代理
1. **API密钥** --从UAVCrew上的MCP连接器详细信息页面旋转K0键
1. **每个租户代币** -每个租户获得独立的API证书（K4）
1. **范围执行** --T1 JWT为每个实体和操作携带范围权限
1. **网络隔离** --在反向代理后绑定到127.0.0.1
______________________________________________________________________
## 故障排除
### 服务器无法启动
uavcrew status sudo journalctl -u mcp-server -f
### UAV机组人员无法连接
1. 检查防火墙是否允许HTTPS（端口443）
1. 验证SSL证书是否有效
1. 测试健康状况： `curl https://your-mcp-domain/health`
1. 检查身份验证模式是否与您的UAVCrew配置匹配
### 配置更改未生效
uavcrew restart
______________________________________________________________________
## 支持
- **文档**: https://docs.uavcrew.ai/mcp
- **问题**: https://github.com/uavopsys/uavcrew-mcp-server/issues
- **电子邮件**: support@uavcrew.ai
______________________________________________________________________
## 许可证
MIT许可证——见 [许可证](LICENSE) 文件。