Skybrary MCP

SKYbrary MCP

A. 模型上下文协议（MCP） 该服务器使人工智能助手能够结构化地访问SKYbrary航空安全数据，包括超过1500份事故和事件报告的语义搜索索引。

它做什么

MCP服务器向Claude（或任何与MCP兼容的AI）公开了六个工具：

建筑

Claude Desktop / AI client
        │
        │  MCP (stdio)
        ▼
  SKYbrary MCP server (Node.js)
        │
        ├──► skybrary.aero  (live article fetch + 30-day cache)
        │
        ├──► Ollama  (embeddings for search_accidents queries)
        │
        └──► ChromaDB  (vector index of ~1,500 accident reports)

MCP服务器在本地运行。Ollama和ChromaDB可以在本地或远程机器上运行（例如，带有GPU的Linux机器）。看 README-remote-rag.md 获取远程设置指南。

先决条件

• Node.js 20+
• SKYbrary账户（用于构建RAG指数）
• 奥拉玛 随着 mxbai-embed-large 拉
• ChromaDB （推荐使用Docker）
• Python 3.11+（用于数据管道脚本）

快速开始

1.安装和构建

pnpm install
pnpm run build

2.启动Olama和ChromaDB

docker compose up -d

这将开始：

• 奥拉玛 在端口11434上（如果有GPU）和自动拉取 mxbai-embed-large
• ChromaDB 在端口8000上，将数据持久化到 data/rag/chroma/

3.构建静态MCP数据文件（一次性）

pip install -r scripts/mcp/requirements.txt
python scripts/mcp/populate_operational_issues.py
python scripts/mcp/populate_human_performance.py

输出： data/operational_issues.json, data/human_performance.json，以及关键字映射文件。

4.构建RAG索引（一次性，需要SKYbrary证书）

pip install -r scripts/rag/requirements.txt

# Set credentials once for this shell session
export SKYBRARY_USER="you@example.com"
read -s SKYBRARY_PASS
export SKYBRARY_PASS

# 4a. Fetch the list of all accident/incident slugs
python scripts/rag/populate_accidents_incidents.py

# 4b. Fetch and parse each article into structured JSON
python scripts/rag/process_accidents.py --resume

# 4c. Embed and store in ChromaDB
python scripts/rag/embed_accidents.py --resume

输出： data/rag/processed/*.json （每份报告一个文件），然后在ChromaDB中存储向量。

5.配置克劳德桌面

增添 claude_desktop_config.json （通常在 ~/Library/Application Support/Claude/claude_desktop_config.json 在macOS上）：

{
  "mcpServers": {
    "skybrary": {
      "command": "node",
      "args": ["/absolute/path/to/SKYbrary-MCP/dist/index.js"]
    }
  }
}

如果Ollama和ChromaDB位于远程计算机上，请添加 env 块：

{
  "mcpServers": {
    "skybrary": {
      "command": "node",
      "args": ["/absolute/path/to/SKYbrary-MCP/dist/index.js"],
      "env": {
        "OLLAMA_URL": "http://YOUR_RAG_HOST:11434",
        "CHROMA_URL": "http://YOUR_RAG_HOST:8000"
      }
    }
  }
}

环境变量

文件结构

SKYbrary-MCP/
├── src/
│   ├── index.ts          # MCP server — all tools defined here
│   └── cacheManager.ts   # 30-day disk cache for safety articles
├── dist/                 # Compiled JS (npm run build)
├── data/
│   ├── operational_issues.json
│   ├── operational_issues_map.json
│   ├── human_performance.json
│   ├── human_performance_map.json
│   ├── accidents_incidents.json   # slug list (from pipeline step 4a)
│   ├── cache/                     # cached safety articles
│   └── rag/
│       ├── processed/             # structured JSON per report (step 4b)
│       └── chroma/                # ChromaDB vector store (step 4c)
├── scripts/
│   ├── mcp/              # Scripts for static MCP data files
│   │   ├── populate_operational_issues.py
│   │   ├── populate_human_performance.py
│   │   └── requirements.txt
│   └── rag/              # Scripts for the RAG index
│       ├── populate_accidents_incidents.py
│       ├── process_accidents.py
│       ├── embed_accidents.py
│       └── requirements.txt
├── docker-compose.yml    # Ollama + ChromaDB services
├── README.md
└── README-remote-rag.md  # Guide for running Ollama/ChromaDB on a remote Linux machine

典型的人工智能工作流程

当用户粘贴事故/事件报告时，人工智能应该：

1. 呼叫 get_accident_analysis_template 获取分析工作流程
2. 呼叫 list_operational_issues 和 list_human_performance 获取类别名称和代码
3. 将报告的事件类型代码映射到类别；呼叫 list_keywords 对于每一个
4. 可选呼叫 get_safety_article 有关相关关键字的完整定义
5. 呼叫 search_accidents 寻找类似的历史事件
6. 呼叫 get_accident_report 关于任何有趣的结果，请阅读完整的报告章节
7. 根据调查结果生成安全建议，进行结构化分析

更新索引

RAG指数（新事故/事件报告）

当新的SKYbrary报告发布时：

python scripts/rag/populate_accidents_incidents.py --resume
python scripts/rag/process_accidents.py --resume
python scripts/rag/embed_accidents.py --resume

MCP数据文件（分类法更改）

如果SKYbrary更新了其操作问题或人员绩效分类，请重新生成静态JSON文件：

pip install -r scripts/mcp/requirements.txt
python scripts/mcp/populate_operational_issues.py
python scripts/mcp/populate_human_performance.py

输出： data/operational_issues.json, data/operational_issues_map.json, data/human_performance.json, data/human_performance_map.json.

发展

pnpm run dev   # Launch MCP Inspector for interactive tool testing