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.jsonobservatories/--天文台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(...)- 发现可用的天文台
- 加载天文台的完整目录和说明
- 检查数据集参数以选择要获取的内容
- 获取某个时间范围的数据--返回文件路径+统计信息
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许可证
麻省理工学院