AI导哈

航空数据智能分析系统

一个基于n8n工作流、MCP工具和Groq代理的航空数据智能分析系统，旨在为旅客和运营团队提供航班状态和异常检测服务。

  • by BitwiseTitan
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 BitwiseTitan/Simple-MCP-n8n-Implementation

使用说明

简易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 旅行者和运营人员可以在那里问自然语言问题。

结果是一个紧凑、可扩展的示例 基于实时航空数据的人工智能系统.

系统架构

高水位流量：

  1. n8n 定期调用航空数据API（例如OpenSky），对响应进行规范化，并存储每个区域的最新快照。
  2. n8n公开HTTP 网络钩子 （例如。 REGION1_WEBHOOK)它总是以JSON格式返回最新快照。
  3. 这 MCP服务器 (server.py)定义了在内部调用这些webhook并返回强类型结果的工具。
  4. Groq代理商 (agents.py)通过工具调用调用这些工具。
  5. 这 流线型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 < 100 m/s).
    • 旗帜 非常高的爬升/下降率 （例如。 vertical_rate > 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(...)

  1. 发送a system_prompt 和 user_query 再加上模型中允许的工具。
  2. 如果模型返回 tool_calls，解析每个调用，通过执行 execute_tool，并将结果附加为 tool 信息。
  3. 使用对话（包括工具输出）再次调用模型以生成最终答案。

混凝土外加剂

  • 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 一个问题集中在乘客的航班上。
      2. 呼叫 ops_agent 在该航班周围进行更广泛的区域SITREP。
      3. 用两名特工的反应进行最后的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上，视频可以通过相对路径嵌入，例如：

![Project demo](demo.mp4)

此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 用于单命令部署。

相关 MCP