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)提供两个角色：

- 旅行者：专注于单个呼号。 - 运维：重点关注区域交通和异常情况。

架构图（来自作业，在此处实现）：

Overall workflow

其他检查器/调试视图：

• 代理工具调用检查器：\

Agent tests

• MCP检查器/HTTP流：\

MCP inspector

______________________________________________________________________

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(...)

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 一个问题集中在乘客的航班上。 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上，视频可以通过相对路径嵌入，例如：

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