晴空

一种模型上下文协议（MCP）服务器，融合实时航空、运营、天气和政策数据，以跟踪和减轻旅行中断。

](https://www.docker.com/) ![API](http://localhost:3000/api/tools) ![License](LICENSE)

概述

Clear Skies将“硬操作”信号（ATC程序、航班延误、天气）与“软环境”（劳工行动、国际咨询）相结合，为旅行者提供：

风险评分： 运营、天气、TSA和新闻的加权分析
可操作的见解： 基于等级的建议（绿色/黄色/红色）
简明简报： 没有原始的API垃圾-只有什么才重要

非常适合想要了解以下信息的旅行者： *“我的旅行看起来不错，还是我需要一个备用计划？”*

数据源

所有API都是集成的，并使用免费层：

航班： 航空烟囱（每月100次请求，实时航班数据）
天气： WeatherAPI.com （每月100万次请求，METAR/TAF预测）
安全： 美国运输安全管理局API （公共API，检查点等待时间）+ 人工智能驱动的新闻回退 🆕
新闻： 新闻数据.io （200个请求/天，旅行中断新闻）
意图解析： Google Gemini API （60个请求/分钟，自然语言处理）

🆕 AI驱动的安全新闻解释器

当TSA API不可用时，Clear Skyes自动使用 双子座AI 分析机场安全头条新闻并提取可操作的情报。该系统搜索有关安全线路、中断、人员配置问题和系统中断的新闻，然后使用人工智能对风险进行评分并提供建议。

了解更多： 新闻_口译员.md

设置

先决条件

Node.js v20+
API密钥：aviationstack，WeatherAPI，newsdata.io，Google Gemini

安装

npm install

配置

创建一个 .env 项目根目录中的文件：

# Required API Keys (all have free tiers)
AVIATIONSTACK_KEY=your_key_here          # Get at: https://aviationstack.com/
WEATHERAPI_KEY=your_key_here             # Get at: https://www.weatherapi.com/
NEWSDATA_KEY=your_key_here               # Get at: https://newsdata.io/
GEMINI_API_KEY=your_key_here             # Get at: https://ai.google.dev/

# TSA API (public, no key needed)
MYTSA_APP=https://apps.tsa.dhs.gov/MyTSAWebService/GetConfirmedWaitTimes.ashx

# Server Configuration
MCP_WS_HOST=0.0.0.0
MCP_WS_PORT=3000
NODE_ENV=production

免费等级限制：

Aviationstack:每月100次API调用
WeatherAPI：每月100万次API调用
Newsdata.io:200个API调用/天
双子座：60个请求/分钟
TSA：无限制（公共API）

构建

npm run build

用法

Web前端

使用Clear Skies最简单的方法是通过web界面：

启动服务器：

npm run dev:http

打开浏览器：

http://localhost:3000

问一个问题：

-类型：“查看我明天从肯尼迪机场起飞的AA123航班” -点击“分析风险” -使用可视化图表查看全面的风险分析

前端功能：

Gemini AI支持的自然语言输入
动画风险评分可视化
部件故障和关键信号
可采取行动的建议
移动响应式设计

看 public/README.md 用于前端文档。

部署选项

选项1：带Web前端的HTTP REST API（推荐）

# Development
npm run dev:http

# Production
npm run build
npm run start:http

访问web UI http://localhost:3000 或者直接使用API端点。

选项2:MCP stdio服务器（适用于克劳德桌面）

npm run dev

选项3:Docker（用于生产部署）

docker compose up -d

看部署.md 获取完整的部署指南。

HTTP API终结点

服务器运行后（默认值： http://localhost:3000):

健康检查：

curl http://localhost:3000/health

获取风险简报：

curl -X POST http://localhost:3000/api/tools/risk_brief \
  -H "Content-Type: application/json" \
  -d '{
    "flightIata": "AA123",
    "date": "2025-11-09",
    "depIata": "JFK",
    "paxType": "domestic"
  }'

\*\*解读安全新闻（人工智能驱动）：

curl -X POST http://localhost:3000/api/tools/interpret_security_news \
  -H "Content-Type: application/json" \
  -d '{"iata": "LAX"}'

列出所有工具：

curl http://localhost:3000/api/tools

MCP客户端使用情况（stdio）

对于像Claude Desktop这样的MCP兼容客户端：

npm run prompt risk_brief '{
  "flightIata": "AA123",
  "date": "2025-11-09",
  "depIata": "JFK",
  "paxType": "domestic"
}'

输出： 结构化JSON，包含风险评分、级别、组件细分、顶级信号和建议。

解析自然语言

将用户问题转化为结构化意图：

npm run prompt parse_intent '{
  "text": "Check my flight AA123 tomorrow from JFK; if risky hold a hotel."
}'

可用的API工具

服务器通过HTTP REST API公开了14个工具：

核心工具

risk_brief -综合出行风险分析（主要工具）

-结合航班、天气、TSA和新闻数据 -退货风险评分（0-100）和等级（绿色/黄色/红色） -提供可操作的建议

parse_intent -自然语言查询解析器

-将用户问题转换为结构化JSON -由谷歌Gemini AI提供技术支持

数据工具

flight_status -实时航班信息

-实时出发/到达时间 -延误、登机口、航站楼 -航班状态（计划、活动、降落）

airport_weather -机场天气预报

-当前状况和3天预测 -温度、风、降水 -航空特定危害

tsa_wait_times -TSA检查站等待时间

-按终端划分的当前等待时间 -历史格局 -高峰时段建议 \- API不可用时自动新闻回退 🆕

interpret_security_news - 🆕 基于人工智能的安全分析

-使用Gemini AI分析新闻标题 -提取安全/中断情报 -风险评分和建议 -信心评估

news_search -旅游中断新闻

-航空公司罢工，空中交通管制延误 -机场关闭、天气事件 -政策变化和建议

动作工具

search_backup_flights -替代航班选择
search_nearby_hotels -灵活取消的酒店
get_rebooking_policy -航空公司变更政策
generate_mitigation_plan -优先行动计划

AI摘要工具

summarize_risk_with_llm -自然语言风险总结
summarize_weather_with_llm -会话式天气预报
generate_travel_brief -结合所有数据的完整旅行简报

看部署.md 获取完整的API文档和示例。

工作流示例

用户询问： *“我明天的AA123航班看起来有风险吗？”*
解析意图： 提取航班、日期、出发地
获取风险简报： 获取所有数据，计算分数
退货分析： “黄色层-出发时有雷暴，提前45分钟到达”

发展

# Run HTTP API in dev mode (for web frontends)
npm run dev:http

# Run MCP stdio server in dev mode (for Claude Desktop)
npm run dev

# Test all tools
npm run test:all

# Interactive testing
npm run prompt

Docker部署

快速入门（本地）

# Build and start the server
docker compose up --build -d

# Check container status
docker compose ps

# View logs
docker compose logs -f

# Stop the server
docker compose down

API将于 http://localhost:3000

API测试示例

# Health check
curl http://localhost:3000/health

# List all available tools
curl http://localhost:3000/api/tools

# Get real-time flight status
curl -X POST http://localhost:3000/api/tools/flight_status \
  -H "Content-Type: application/json" \
  -d '{"flightIata": "AA100", "date": "2025-11-09"}'

# Get comprehensive risk brief
curl -X POST http://localhost:3000/api/tools/risk_brief \
  -H "Content-Type: application/json" \
  -d '{
    "flightIata": "AA100",
    "date": "2025-11-09",
    "depIata": "JFK",
    "paxType": "domestic"
  }'

# Search travel news
curl -X POST http://localhost:3000/api/tools/news_search \
  -H "Content-Type: application/json" \
  -d '{"query": "airline strike"}'

# Get airport weather
curl -X POST http://localhost:3000/api/tools/airport_weather \
  -H "Content-Type: application/json" \
  -d '{"iata": "JFK"}'

生产部署（Vultr/VPS）

逐步部署：

SSH连接到您的服务器：

ssh root@your-vultr-ip

安装Docker：

curl -fsSL https://get.docker.com -o get-docker.sh sh get-docker.sh apt-get install docker-compose-plugin

克隆和配置：

git clone https://github.com/Harshit-Saini0/clear-skies.git cd clear-skies nano .env # Add your API keys

配置防火墙：

ufw allow 3000/tcp ufw reload

构建并运行：

docker compose up --build -d

验证部署：

curl http://your-vultr-ip:3000/health

管理命令：

# View logs
docker compose logs -f

# Restart
docker compose restart

# Update after code changes
git pull origin main
docker compose up --build -d

# Check resource usage
docker stats

看部署.md 用于：

带有SSL/HTTPS的Nginx反向代理
使用Let's Encrypt设置域名
使用PM2或systemd进行流程管理
生产监控和故障排除
完整的API参考文件

建筑

HTTP REST API： 用于web前端的Express.js服务器(src/http-server.ts)
MCP服务器： 用于Claude Desktop的带有stdio传输的TypeScript(src/server.ts)
提示网关： 用于NLP的Gemini API→ 结构化JSON
风险引擎： 5个维度的加权评分
提供程序适配器： 每个API的类型包装器
部署： Docker、Docker Compose或独立的Node.js

前端集成

JavaScript/RReact示例

const API_URL = 'http://your-vultr-ip:3000';

async function getRiskBrief(flightIata, date) {
  const response = await fetch(`${API_URL}/api/tools/risk_brief`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      flightIata,
      date,
      depIata: 'JFK',
      paxType: 'domestic'
    })
  });
  
  const result = await response.json();
  if (result.success) {
    console.log('Risk Score:', result.data.totalScore);
    console.log('Risk Tier:', result.data.tier);
    return result.data;
  } else {
    throw new Error(result.error);
  }
}

// Usage
getRiskBrief('AA100', '2025-11-09')
  .then(data => console.log('Risk Analysis:', data))
  .catch(err => console.error('Error:', err));

Python示例

import requests

API_URL = 'http://your-vultr-ip:3000'

def get_risk_brief(flight_iata, date):
    response = requests.post(
        f'{API_URL}/api/tools/risk_brief',
        json={
            'flightIata': flight_iata,
            'date': date,
            'depIata': 'JFK',
            'paxType': 'domestic'
        }
    )
    result = response.json()
    if result['success']:
        return result['data']
    else:
        raise Exception(result['error'])

# Usage
data = get_risk_brief('AA100', '2025-11-09')
print(f"Risk Score: {data['totalScore']}")
print(f"Risk Tier: {data['tier']}")

API响应格式

所有端点返回结构一致的JSON：

成功响应：

{
  "success": true,
  "data": {
    // Tool-specific data here
  }
}

错误响应：

{
  "success": false,
  "error": "Error message description"
}

项目状态

✅ 用于web前端的HTTP REST API\ ✅ 核心风险评分引擎\ ✅ 多源数据融合（5个API）\ ✅ 实时飞行数据（Aviationstack）\ ✅ 天气预报（WeatherAPI）\ ✅ 旅游新闻（Newsdata.io）\ ✅ TSA等待时间\ ✅ 人工智能驱动的安全新闻解读 🆕\ ✅ 使用Gemini AI自动TSA回退 🆕\ ✅ MCP标准传输\ ✅ Gemini AI意图解析和总结\ ✅ Docker容器化\ ✅ 自动错误处理和回退\ ✅ 响应缓存（30s-1小时）\ 🔜 限速中间件\ 🔜 WebSocket支持实时更新\ 🔜 身份验证/API密钥\ 🔜 增强的备份搜索（酒店、备用航班）

性能和缓存

航班数据： 30秒缓存
机场数据： 1小时缓存
天气数据： 10分钟缓存
新闻数据： 10分钟缓存
响应时间： 平均\<2秒

安全说明

⚠️ 生产：

添加API身份验证（API密钥或JWT）
为您的域正确配置CORS
使用带有SSL证书的HTTPS
实施速率限制
永不承诺 .env 文件到git
使用特定于环境的API密钥

故障排除

常见问题

端口3000已在使用中：

lsof -i :3000
kill -9

Docker构建失败：

docker compose down
docker system prune -a
docker compose up --build -d

API返回403个错误：

在中检查API密钥 .env 文件
验证是否未超过可用层限制
Aviationstack：每月100次通话限制
Newsdata.io:200次通话/天限制

容器不断重新启动：

docker compose logs --tail=50
# Check for missing environment variables or API key issues

API费率限制（免费等级）

API	自由层限制	缓存
Aviationstack	每月100次	30秒（航班），1小时（机场）
WeatherAPI	每月1M	10分钟
新闻数据.io	200/天	10分钟
双子座	60/分钟	无
TSA	无限制	1小时

支持和文档

完整部署指南： 部署.md
API参考： http://your-server:3000/api/tools
问题：

技术栈

运行时间： Node.js 20+与TypeScript
服务器： Express.js（HTTP）+MCP SDK（stdio）
API： Aviationstack、WeatherAPI、Newsdata.io、TSA、Gemini
缓存： LRU缓存
部署： Docker+Docker组合
运输： HTTP REST（网络）+stdio（克劳德桌面）

贡献

欢迎投稿！拜托：

分叉存储库
创建要素分支
提交拉取请求

见项目规范 DEPLOYMENT.md 详细的设计目标。

许可证

麻省理工学院-参见许可证详情

______________________________________________________________________

内置于❤️ 对于希望在交通中断之前保持领先的旅行者

Clear Skies

快速接入

详细介绍

晴空

概述

数据源