使用说明

无人机乘员MCP网关

宣言驱动的MCP网关，使UAVCrew的人工智能代理能够通过现有的REST API安全访问您的无人机操作数据。

概述

网关运行 您的基础设施 并将MCP工具调用转换为针对REST API的经过验证的HTTP请求。UAVCrew的AI代理使用HTTPS连接模型上下文协议读取、搜索数据并对其采取行动，而无需直接访问数据库。

┌─────────────────────────────────────────────────────────────────┐
│  YOUR INFRASTRUCTURE                                            │
│                                                                 │
│  ┌──────────────┐    ┌──────────────┐    ┌──────────────┐      │
│  │ Your REST    │    │ MCP Gateway  │    │   HTTPS      │      │
│  │ API (Django, │<───│  Port 8400   │<───│  Nginx/Caddy │<─────┼── UAVCrew AI
│  │  Rails, etc) │    │  (gunicorn)  │    │  Port 443    │      │
│  └──────────────┘    └──────────────┘    └──────────────┘      │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

您的数据保留在您的网络上。 网关仅转发合规性分析所需的API调用。

安装

1.克隆和安装

git clone https://github.com/uavopsys/uavcrew-mcp-server.git
cd uavcrew-mcp-server

python3 -m venv venv
source venv/bin/activate

pip install .

2.运行安装向导

uavcrew setup

向导将：

配置服务器标识和公共URL
设置清单路径和客户端API基本URL
配置身份验证模式
保存 .env 配置
生成反向代理配置（Caddy/Nginx/Apache）
创建并安装systemd服务

3.启动并验证

uavcrew start
uavcrew status
curl http://localhost:8400/health

预期响应：

{
  "status": "healthy",
  "service": "mcp-gateway",
  "version": "2.0.0",
  "entities": 12,
  "auth_mode": "jwt",
  "token_resolution": "dynamic"
}

4.生成K0 API密钥

在MCP网关可以运行之前，您需要 K0 API密钥 无人机机组人员。此密钥允许您的应用程序管理租户和提供AI访问。每个K0键都绑定到特定的MCP连接器上。

去你的无人机机组仪表板→ MCP网关
点击您的MCP连接器
在 K0 API密钥 卡片，点击 生成K0
复制密钥——这是唯一一次显示它

您的应用程序使用此密钥调用UAVCrew的租户管理API：

POST https://api.uavcrew.ai/v1/tenants
X-API-Key: uav_YOUR_K0_KEY
Content-Type: application/json

{
  "name": "Your Organization",
  "external_id": "your-org-uuid"
}

这在UAVCrew中创建一个租户，并提供一个租户聊天API密钥（K1）。 K0键具有 tenants:write 和 tenants:read 范围--常规聊天键 (chat:read, chat:write)无法管理租户。

要旋转K0键，请单击 旋转K0 在同一连接器详细信息页面上。上一个密钥立即被撤销。

在应用程序的环境中设置K0键：

变量	值
`UAVCREW_API_URL`	`https://api.uavcrew.ai` （或您的UAVCrew实例URL）
`UAVCREW_PLATFORM_API_KEY`	MCP连接器中的K0键

5.注册无人机机组人员

首选无人机机组仪表板→ MCP网关
点击注册 --输入服务器名称、公共URL和集成类型
- 平台（多租户）：您的应用程序为多家公司提供服务。您可以通过K0密钥管理租户，并动态解析每个租户的令牌（K4）
- 直接（单一公司）：你的应用程序服务于一家公司。集 CLIENT_API_TOKEN 在 .env
复制连接令牌并将其设置为 MCP_API_KEY 在你的 .env
对于多租户连接器：从连接器详细信息页面生成K0密钥（上述步骤4）

UAVCrew使用K3公钥验证的T1委托JWT进行连接（随此回购在 keys/k3_public.pem).无需手动进行代币交换。

管理

uavcrew start       # Start the service
uavcrew stop        # Stop the service
uavcrew restart     # Restart after config changes
uavcrew status      # Check health, entities, auth mode

# View logs
sudo journalctl -u mcp-server -f

更新

cd /opt/ayna/uavcrew-mcp-server
git pull
source venv/bin/activate
pip install .
uavcrew restart

发展

cd /opt/ayna/uavcrew-mcp-server
source venv/bin/activate
pip install -e ".[dev]"

make dev       # Start with gunicorn --reload
make test      # Run tests
make lint      # Run linter

源代码更改已生效 --reload健康检查： curl http://localhost:8400/health.

CLI命令

命令	描述
`uavcrew setup`	交互式配置向导
`uavcrew start`	启动网关服务（systemd）
`uavcrew stop`	停止网关服务（systemd）
`uavcrew restart`	重新启动网关服务（systemd）
`uavcrew status`	显示状态、实体、身份验证模式和服务运行状况
`uavcrew keys list`	列出已配置的API密钥
`uavcrew keys add <token>`	从UAVCrew添加API密钥
`uavcrew keys remove <prefix>`	删除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.示例获取带有auth模式文档的完整模板。

清单

网关由 manifest.json 声明实体、API路径和可用操作的文件。看 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 在 .envUAVCrew通过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)可以为您生成这些配置。

安全

超文本传输安全协议 --始终使用TLS终止的反向代理
API密钥 --从UAVCrew上的MCP连接器详细信息页面旋转K0键
每个租户代币 -每个租户获得独立的API证书（K4）
范围执行 --T1 JWT为每个实体和操作携带范围权限
网络隔离 --在反向代理后绑定到127.0.0.1

故障排除

服务器无法启动

uavcrew status
sudo journalctl -u mcp-server -f

UAV机组人员无法连接

检查防火墙是否允许HTTPS（端口443）
验证SSL证书是否有效
测试健康状况： curl https://your-mcp-domain/health
检查身份验证模式是否与您的UAVCrew配置匹配

配置更改未生效

uavcrew restart

支持

文档: https://docs.uavcrew.ai/mcp
问题: https://github.com/uavopsys/uavcrew-mcp-server/issues
电子邮件: support@uavcrew.ai

许可证

MIT许可证——见许可证文件。