简易MCP–n8n空域副驾驶
这个项目是 最小端到端空域副驾驶 连接：
- n8n工作流 其定期获取飞行数据（例如从OpenSky）并通过HTTP webhooks公开。
- 一 MCP服务器 (
server.py)它将这些Webhook包装为强类型的MCP工具。 - Groq支持的代理商 (
agents.py)调用这些工具来推理航班状态和异常。 - A. 流线型UI (
ui_app.py)这让旅行者和运营人员可以在浏览器中与系统进行交互。
它被设计为一个简单但完整的示例 代理工具+工作流堆栈：数据流来自n8n→ MCP工具→ 代理→ UI.
______________________________________________________________________
引言与问题陈述
现代航空公司运营和乘客都可以访问原始航班跟踪数据，但：
- 乘客 很难将高度、速度和位置解释为“我的航班还好吗？”
- 运营团队 需要一个简明的视图 区域交通与异常 而不是原始状态向量。
- 许多系统 紧密耦合 到单个API，并且在以下各项之间缺乏干净的分离：
- 数据收集（预定工作流）， - 工具接口（MCP）， - 推理（LLM代理）， - 用户体验（UI）。
该项目通过以下方式解决了这一差距：
- 使用 n8n 定期获取和缓存飞行快照。
- 将这些快照公开为 MCP工具 任何代理或客户都可以致电。
- 建筑 Groq代理商 可以调用工具并相互协调。
- 提供a 简单的web UI 旅行者和运营人员可以在那里问自然语言问题。
结果是一个紧凑、可扩展的示例 基于实时航空数据的人工智能系统.
______________________________________________________________________
系统架构
高水位流量：
- n8n 定期调用航空数据API（例如OpenSky），对响应进行规范化，并存储每个区域的最新快照。
- n8n公开HTTP 网络钩子 （例如。
REGION1_WEBHOOK)它总是以JSON格式返回最新快照。 - 这 MCP服务器 (
server.py)定义了在内部调用这些webhook并返回强类型结果的工具。 - Groq代理商 (
agents.py)通过工具调用调用这些工具。 - 这 流线型UI (
ui_app.py)提供两个角色：
- 旅行者：专注于单个呼号。 - 运维：重点关注区域交通和异常情况。
架构图（来自作业，在此处实现）：
其他检查器/调试视图：
- 代理工具调用检查器：\
- MCP检查器/HTTP流：\
______________________________________________________________________
n8n工作流和快照存储
n8n工作流（未存储在此仓库中）负责：
- 正在获取数据 按照时间表（例如每N秒）从航空API获得。
- 转型 将原始状态向量转换为归一化快照形状：
- region：区域标识符（例如。 "region1"). - snapshot_time：快照的Unix时间戳。 - fetched_at_iso：n8n获取它的ISO8601时间戳。 - flight_count：航班数量。 - flights：带有以下键的航班字典列表 icao24, callsign, origin_country, latitude, longitude, geo_altitude, velocity, vertical_rate, on_ground等等。
- 缓存 内存中的最新快照或n8n内的简单存储。
- 暴露 每个区域通过HTTP webhook端点获取的最新快照：
- 例子： http://localhost:5678/webhook/latest-region1
在这个项目中，Python代码从不直接与OpenSky对话。相反，它相信 n8n拥有数据收集和缓存，并通过HTTP按需提取最新快照。
______________________________________________________________________
MCP服务器和工具(server.py)
MCP服务器使用 FastMCP (mcp.server.fastmcp.FastMCP)并使用 streamable-http 运输。
- 类型定义 （通过
typing_extensions.TypedDict):
- Flight：一架飞机的状态，字段如下 icao24, callsign, origin_country, latitude, longitude, geo_altitude, velocity, vertical_rate, on_ground等等。 - Snapshot：包含元数据和列表的区域快照 Flight. - FlightLookupResult：元数据+可选 flight +人类可读的信息。 - Alert 和 AlertResult：异常描述和严重程度。
- Webhook配置:
- REGION_WEBHOOKS 是一个将区域ID映射到webhook URL的字典。 - URL可以通过环境变量覆盖，例如： - REGION1_WEBHOOK （默认值： http://localhost:5678/webhook/latest-region1).
- 内部助手:
- _fetch_snapshot(region): - 验证该区域是否存在。 - 使用以下命令调用配置的n8n webhook requests. - 确保 region 和 flight_count 字段存在。
暴露的MCP工具：
flights_list_region_snapshot(region: str = "region1") -> Snapshot\
返回给定区域的最新缓存快照。
flights_get_by_callsign(callsign: str, region: str = "region1") -> FlightLookupResult
- 在最新快照中搜索 callsign. - 返回一个结果： - flight （或 None), - message 描述结果， - region, snapshot_time，以及 fetched_at_iso.
alerts_list_active(region: str = "region1") -> AlertResult\
基于规则的简单异常检测：
- 旗下航班 高空低速 （例如。 alt > 8000 和 velocity 20 或 < -20 m/s）。
这些工具是代理和外部MCP客户端看到的；它们将n8n的细节隐藏在干净的工具界面后面。
______________________________________________________________________
代理、提示和A2A沟通(agents.py)
代理是通过以下方式实现的 Groq's 聊天完成 工具调用.
- 工具注册表(
TOOLS)：描述了标准函数调用模式中的MCP工具（名称、描述、参数）。 execute_tool(name, arguments)：将工具调用从LLM路由到中的实际Python实现server.py.- Groq客户:
- 通过配置 GROQ_API_KEY （环境变量）。 - 创建缓慢，以便导入 agents.py 如果密钥丢失，不会立即失败。
通用工具调用循环： run_tool_calling_chat(...)
- 发送a
system_prompt和user_query再加上模型中允许的工具。 - 如果模型返回
tool_calls，解析每个调用，通过执行execute_tool，并将结果附加为tool信息。 - 使用对话（包括工具输出）再次调用模型以生成最终答案。
混凝土外加剂
traveler_agent(question: str)
- Persona：旅行者支持。 - 提示：解释说，客服应该帮助乘客了解他们的航班在哪里，高度和速度，以及是否有任何异常。 - 工具：仅限于 flights_get_by_callsign.
ops_agent(question: str)
- Persona：航空公司运营/调度员。 - 提示：重点关注区域安全、交通水平和异常情况。 - 工具： flights_list_region_snapshot 和 alerts_list_active.
traveler_with_ops(callsign: str, passenger_question: str)
- 多代理编排模式： 1. 呼叫 traveler_agent 一个问题集中在乘客的航班上。 1. 呼叫 ops_agent 在该航班周围进行更广泛的区域SITREP。 1. 用两名特工的反应进行最后的Groq通话，以进行综合 一个协调的答案 对于乘客。
这个结构清晰地展示了 代理对代理（A2A）通信 在共享MCP工具之上。
______________________________________________________________________
UI设计和用户体验(ui_app.py)
UI使用 溪流 并在以下位置显示两个主要选项卡 http://localhost:8501:
- 旅行者视图-“个人航班监视器”
- 输入： - 航班呼号（例如。 PIA293). - 免费短信乘客问题（例如“我的航班在哪里，一切正常吗？”）。 - 行动： - 获取当前航班数据（仅限工具）: - 呼叫 flights_get_by_callsign 并显示了原始工具JSON。 - 询问旅行社: - 向发送自然语言问题 traveler_agent，这可能会使用工具。 - 询问旅行者+运营（协调）: - 用途 traveler_with_ops 结合旅行者和运营商的观点。
- 操作视图-“空域操作副驾驶”
- 输入： - 区域选择器（目前仅 region1). - 行动： - 获取最新快照: - 呼叫 flights_list_region_snapshot 并显示： - 区域元数据(region, snapshot_time, flight_count). - 飞行数据帧（呼号、国家、高度、速度、地面）。 - 分析异常情况: - 呼叫 alerts_list_active 并显示了异常飞行表（高度、速度、垂直速率、原因、严重程度）。 - 向运营代理询问SITREP: - 呼叫 ops_agent 总结区域交通并突出关键航班。
此UI为这两个角色提供了 透明视图：他们可以看到原始工具输出和高级代理答案。
______________________________________________________________________
演示视频和媒体
目录包含：
- 端到端演示:
demo.mp4–MCP+n8n+代理+UI工作流程的演练。 - 检查员演示:
testing_inspector.mp4–重点介绍MCP/代理检验员工具。
在GitHub上，视频可以通过相对路径嵌入，例如：
此README中包含的截图：
successful_workflow.png–整体架构。agents_test.png–代理工具调用测试。mcp_inspector.png–MCP检查器/HTTP视图。
______________________________________________________________________
限制和未来改进
- 单一区域：仅
region1默认情况下是有线的，尽管代码通过以下方式支持其他区域REGION_WEBHOOKS. - 简单异常规则：检测是基于阈值的（速度与高度、垂直速率），而不是学习的。
- 无历史分析：只使用最新快照；趋势和时间序列分析超出了范围。
- 外部工作流：假设n8n工作流存在，但在此存储库中不进行版本控制。
- 最小错误处理：简化了网络故障、格式错误的响应和速率限制处理，以保持示例的重点。
未来可能的改进：
- 添加 多区域支持 以及区域和webhooks的配置文件。
- 插入a 数据库 或时间序列存储，用于分析趋势和重复出现的异常。
- 将手写规则替换为 数据驱动异常检测器 （例如，监督或无监督的机器学习）。
- 添加 身份验证/授权 到MCP服务器和UI。
- 使用以下方式打包堆栈（n8n+MCP服务器+UI） Docker Compose 用于单命令部署。