GraceDB

GraceDB MCP 服务

一个开源的 Model Context Protocol（MCP）服务，可将来自 GraceDB 的 LIGO/Virgo/KAGRA 引力波警报提供给大模型 Agent。它将官方 ligo-gracedb 客户端与 MCP 标准连接起来，使 Agent 能够查询、分类并获取引力波候选事件的数据。

旨在作为下游信号处理／异常检测流水线的数据摄取层（例如，从仪器故障中分离出天体物理“啁啾”信号）。

工具

工具	功能
search_superevents	按时间范围和显著性（FAR／天体物理概率）搜索近期超级事件。
get_event_metadata	获取完整的超级事件记录及信号源分类（BBH／BNS／NSBH／地面事件）。
download_event_files	下载 GraceDB 事件文件：天区图、p_astro.json、参数估计（PE）结果、日志。
download_strain_data	获取事件 GPS 时间附近来自 GWOSC 的公开应变时间序列。
utc_to_gps	将 ISO-8601 UTC 时间戳转换为 GPS 秒数。
search_catalog_events	按质量、距离、SNR、p_astro 搜索已发布的 GWOSC 目录事件（GWTC-1 至 GWTC-5）。
get_catalog_event	按引力波名称或 GraceDB ID 获取单个事件的信号源参数及 90% 区间。
get_event_labels	用通俗易懂的语言解释 GraceDB 标签（数据质量、审核、撤回、产品就绪）。
check_data_availability	在下载前，检查哪些探测器有该事件或 GPS 时间范围的公开 GWOSC 应变数据。

⚠️ 重要：应变数据的实际来源

GraceDB 不托管原始应变数据。它存储的是事件文件（天区图、分类、参数估计结果）。公开应变时间序列位于 GWOSC，并通过 GPS 时间使用 gwpy 获取。公开应变数据仅适用于已发布的观测运行——最新的低延迟警报暂时没有公开应变数据。download_strain_data 正是如此：它从 GraceDB 读取 t_0，然后从 GWOSC 获取开放数据（并在数据尚未公开时明确说明）。

要求

• Python 3.10+
• mcp、ligo-gracedb、gwosc、python-dotenv
• 可选：gwpy（用于 download_strain_data 和 utc_to_gps），通过 strain extra 安装。

安装

使用 uv 直接从 PyPI 运行：

uvx --from "gracedb-mcp[strain]" gracedb-mcp

或从源码运行：

git clone https://github.com/izabelamaria24/gracedb-mcp.git
cd gracedb-mcp
python -m venv .venv && source .venv/bin/activate
pip install -e ".[strain]"     # omit [strain] if you don't need strain download

配置

将 .env.example 复制为 .env 并进行调整。匿名访问即可获取公开超级事件：

cp .env.example .env

变量	用途
GRACEDB_SERVICE_URL	API 基础 URL（生产环境或 playground）。
GRACEDB_FORCE_NOAUTH	匿名公开访问时设为 true。
GRACEDB_PROXY / GRACEDB_CERT + GRACEDB_KEY	LVK 成员身份验证（X.509）。
GRACEDB_MCP_DATA_DIR	下载文件的写入位置（默认为 ~/.cache/gracedb-mcp；Docker 中为 /data）。

本地运行

gracedb-mcp          # speaks MCP JSON-RPC over stdio

开发

需要 Python 3.11+（mcp 2.x SDK 需要 Python 3.10+）。

pip install -e ".[dev]"
pytest -q            # tests mock the GraceDB client, no network needed

使用 Docker 运行

预构建镜像（linux/amd64 和 arm64）已发布至 GHCR：

docker run --rm -i -v gracedb-data:/data ghcr.io/izabelamaria24/gracedb-mcp:latest

标签	下载大小	内容
latest、X.Y.Z	约 165 MB	包含应变数据下载（gwpy）在内的所有功能。
latest-slim、X.Y.Z-slim	约 60 MB	包含除 download_strain_data 和 utc_to_gps 之外的所有工具。

也可以自行构建（精简版请添加 --build-arg EXTRAS=）：

docker build -t gracedb-mcp .
docker run --rm -i -v gracedb-data:/data gracedb-mcp

连接到 MCP 客户端

Claude Desktop / VS Code（mcp.json）

添加到 MCP 客户端配置中：

{
  "mcpServers": {
    "gracedb": {
      "command": "gracedb-mcp",
      "env": {
        "GRACEDB_FORCE_NOAUTH": "true",
        "GRACEDB_MCP_DATA_DIR": "./data"
      }
    }
  }
}

或者直接运行容器：

{
  "mcpServers": {
    "gracedb": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "-v", "gracedb-data:/data", "ghcr.io/izabelamaria24/gracedb-mcp:latest"]
    }
  }
}

Agent 提示词示例

• “搜索 2023-05-01 至 2023-06-01 期间 FAR 低于 1e-8 的超级事件。”
• “S230518h 的源分类是什么？它更可能是 BBH 还是 NSBH？”
• “下载 S230518h 的天图和 p_astro 文件。”
• “获取 GW150914 附近的 H1 和 L1 应变数据。”
• “GW190814 的质量是多少？这些数值有多确定？”
• “列出总质量低于 10 个太阳质量的 GWTC-3 事件。”
• “S190814bv 是否经过人工检查？它的标签是什么意思？”
• “每个探测器都有 GW190814 的公开应变数据吗？”

RL 环境（实验性）

gw_rl 是一个 Gymnasium 环境，基于此服务获取的应变数据构建。每个回合都会向 Agent 展示一张 1 s 的时频图，并要求其回答 噪声、啁啾 或 故障（答对 +1，答错 -1）。

真实啁啾十分稀少，因此训练时会将合成啁啾注入真实探测器噪声中；真实目录事件则留作评估。啁啾是来自 LALSimulation 的 IMRPhenomD 波形（--chirp imr，默认），或简单的解析扫描信号（--chirp toy）。故障是由 Gravity Spy 标注的真实 LIGO 故障（--glitch real，默认），或正弦高斯突发信号（--glitch synthetic）。

它不属于 PyPI 软件包；请从此代码库的克隆版本运行（需要 pip 25.1+）：

pip install -e . --group rl
python scripts/fetch_training_strain.py --catalog GWTC-3-confident  # small files, a few MB
python scripts/fetch_glitches.py --files 30  # ~3 GB of GWOSC hour files, cached by gwpy
python scripts/train_agent.py --algo ppo mlp cnn --verbose

路线图

• 除 stdio 外，增加 Streamable-HTTP 传输方式，以支持远程部署。
• 为缓存的天图和 p_astro 文件提供 MCP 资源。

免责声明

此项目为非官方项目；与 LIGO、Virgo、KAGRA 或 GraceDB 无关联，也未获得其认可。请遵守 GWOSC 和 GraceDB 的数据使用政策。

如果你使用此服务获取的数据发表研究结果，请注明数据来源： GWOSC（CC BY 4.0）；如果使用故障标签，也请注明 Gravity Spy。

许可证

GPL-3.0-or-later，与其核心依赖项 ligo-gracedb 和 gwpy 一致。