AI导哈

太阳物理数据访问工具

xhelio-cdaweb是一个用于访问NASA CDAWeb太阳物理数据的工具，支持通过Python库或MCP服务器浏览观测站、检查参数和获取CDF数据。

  • by huangzesen
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 huangzesen/xhelio-cdaweb

使用说明

xhelio cdaweb

美国国家航空航天局CDAWeb太阳物理学数据访问——浏览天文台，检查参数，获取CDF数据。

可作为独立的Python库或任何兼容MCP的LLM客户端（Claude Desktop、Cursor、自定义代理）的MCP服务器。

包含什么

  • 65个天文台目录 拥有2900多个数据集——ACE、帕克太阳探测器、太阳轨道器、Wind、MMS、THEMIS、GOES、Voyager等
  • 2880个预构建的参数元数据文件 来自CDF骷髅大师-- browse_parameters 立即工作，无需网络
  • 自动数据验证 --将获取的CDF文件与主CDF元数据进行比较，以检测幻影（有记录但缺失）和无记录（存在但无记录）参数
  • 结构化系统提示 每个天文台——提供LLM关于可用仪器、数据集和时间覆盖的完整背景

天文台目录是直接从CDAWeb REST API天文台组构建的，没有手工策划的映射。

安装

# Library only
pip install xhelio-cdaweb

# With MCP server
pip install xhelio-cdaweb[mcp]

MCP服务器

配置（克劳德桌面、光标等）

{
  "mcpServers": {
    "cdaweb": {
      "command": "xhelio-cdaweb-mcp"
    }
  }
}

使用自定义缓存目录：

{
  "mcpServers": {
    "cdaweb": {
      "command": "xhelio-cdaweb-mcp",
      "args": ["--cache-dir", "/path/to/cache"]
    }
  }
}

或者直接运行：

xhelio-cdaweb-mcp
xhelio-cdaweb-mcp --cache-dir /path/to/cache
python -m cdawebmcp

缓存目录

所有运行时数据都存储在单个根目录下。默认为 ~/.cdawebmcp/.

首次使用时，捆绑的数据（天文台目录和参数元数据）被复制到缓存目录中。这确保了所有的读取和写入都发生在一个可写位置，即使对于来自PyPI的不可编辑安装也是如此。

通过配置 --cache-dir （MCP服务器）或 cdawebmcp.configure() （图书馆）：

import cdawebmcp
cdawebmcp.configure(cache_dir="/path/to/cache")

~/.cdawebmcp/                  # or custom path via configure()
├── observatories/                  # Observatory catalog JSONs (bootstrapped from package)
├── metadata/                  # Parameter metadata JSONs (bootstrapped from package)
├── cdf_cache/                 # Downloaded CDF data files (permanent, reused across fetches)
│   └── ace/mfi/               #   organized by observatory/instrument path
│       └── ac_h2_mfi_2024.cdf
└── overrides/                 # Validation sync results (append-only)
    └── ace/
        └── AC_H2_MFI.json
  • observatories/ --天文台JSON目录。首次使用时从捆绑包数据中启动。
  • metadata/ --参数元数据JSON。首次使用时从捆绑包数据中启动。根据需要从主CDF获取新的元数据。
  • cdf_cache/ --下载CDF文件的永久缓存。一旦下载了CDF文件，就永远不会重新下载。使用 manage_cache(action="clean", category="cdf_cache") 释放磁盘空间。
  • overrides/ --将提取的数据与元数据进行比较的验证结果。仅追加，每个数据集一个JSON。

工具

工具 说明
browse_observatories() 列出所有65个CDAWeb观测站，包括描述、数据集计数和仪器
load_observatory(observatory_id) 获取天文台的完整系统提示（角色说明+完整的数据集目录）
browse_parameters(dataset_id) 浏览数据集中的所有变量——名称、类型、单位、描述，以及验证状态（如果可用）
fetch_data(dataset_id, parameters, start, stop, output_dir) 下载CDF数据，写入文件，返回元数据+每列统计数据（min、max、mean、std、nan_ratio）
manage_cache(action, ...) 缓存管理——状态、清理、刷新元数据、刷新时间范围、重建目录

典型工作流程

browse_observatories  →  load_observatory("ace")  →  browse_parameters("AC_H2_MFI")  →  fetch_data(...)
  1. 发现可用的天文台
  2. 加载天文台的完整目录和说明
  3. 检查数据集参数以选择要获取的内容
  4. 获取某个时间范围的数据--返回文件路径+统计信息

Python库

from cdawebmcp.catalog import browse_observatories
from cdawebmcp.prompts import build_observatory_prompt
from cdawebmcp.metadata import browse_parameters
from cdawebmcp.fetch import fetch_data

# List all 65 observatories
observatories = browse_observatories()

# Get observatory-specific system prompt
prompt = build_observatory_prompt("ace")

# Browse dataset parameters (instant — uses bundled metadata)
params = browse_parameters(dataset_id="AC_H2_MFI")

# Fetch data — returns DataFrames directly
result = fetch_data("AC_H2_MFI", ["Magnitude"], "2024-01-01", "2024-01-02")
mag = result["Magnitude"]
print(mag["data"])       # pandas DataFrame
print(mag["units"])      # "nT"
print(mag["stats"])      # per-column {min, max, mean, std, nan_ratio}

数据验证

当 fetch_data 下载CDF文件时，它会自动将实际数据变量与捆绑的主CDF元数据进行比较。差异记录在 ~/.cdawebmcp/overrides/ 并浮出水面 browse_parameters:

  • 幻影参数 --在元数据中列出，但在实际数据文件中不存在
  • 未记录的参数 --存在于数据文件中，但不存在于官方元数据中

此验证针对每个唯一的CDF源URL运行一次，并构建一个具有完整来源（源文件、URL、时间戳）的仅追加存档。

捆绑数据

数据 计数 描述
天文台目录 65 仪器、数据集、时间覆盖、PI信息
参数元数据 2880 变量名称、类型、单位、填充值、大小
提示模板 2 通用角色+CDAWeb特定工作流说明

所有捆绑的数据都随软件包一起提供，并在首次使用时复制到缓存目录中。浏览时无需网络访问——仅限 fetch_data 需要连接到CDAWeb。

目录更新

从CDAWeb REST API重建：

# Rebuild observatory catalogs (uses CDAWeb observatory groups API)
python -m cdawebmcp.scripts.build_catalog
python -m cdawebmcp.scripts.build_catalog --observatory ace
python -m cdawebmcp.scripts.build_catalog --list

# Rebuild parameter metadata from Master CDFs
python -m cdawebmcp.scripts.build_metadata
python -m cdawebmcp.scripts.build_metadata --observatory psp

发展

pip install -e ".[dev]"
pytest tests/ -v

许可证

麻省理工学院

相关 MCP