空间跟踪MCP服务器
包装MCP服务器 Space-Track.org REST API。建于 FastMCP 和 流式HTTP 运输。提供通用查询工具、谓词发现（modeldef）、GP/TLE、SATCAT和CDM公共的便利工具，具有内置身份验证、会话处理和根据空间跟踪指南的速率限制。
需求
- Python 3.10+
- 空间跟踪帐户（请求 space-track.org)
安装
pip install -e .或与 紫外线:
uv pip install -e .配置（环境）
| 变量 | 必填 | 默认 | 描述 |
|---|---|---|---|
SPACE_TRACK_IDENTITY | 是\* | -- | 空间跟踪用户名 |
SPACE_TRACK_PASSWORD | 是\* | -- | 空间跟踪密码 |
SPACETRACK_USER | 是\* | -- | 标识别名（PRD） |
SPACETRACK_PASS | 是\* | -- | 密码别名（PRD） |
\*使用其中之一 SPACE_TRACK_IDENTITY/SPACE_TRACK_PASSWORD 或 SPACETRACK_USER/SPACETRACK_PASS. | SPACE_TRACK_BASE_URL |没有| https://www.space-track.org/ |API基本URL| | SPACE_TRACK_TIMEOUT_SECONDS |没有| 60 |请求超时| | SPACE_TRACK_USER_AGENT |没有| space-track-mcp/1.0 |用户代理标头| | SPACE_TRACK_ENABLE_CLASS_GUARDRAILS |没有| true |gp历史的软护栏等。 | | SPACE_TRACK_MAX_BYTES_PER_RESPONSE |没有| 26214400 （25MB）|流媒体阈值| | SPACE_TRACK_CACHE_TTL_SECONDS |没有| 21600 （6小时） | Modeldef TTL 缓存 | | SPACE_TRACK_MAX_SATS |没有| 50 |每次传播呼叫的最大卫星数| | SPACE_TRACK_MAX_TIMESTEPS_PER_CALL |没有| 200000 |最大时间步长（例如24小时1秒=86400）| | SPACE_TRACK_MAX_MC_SAMPLES |没有| 2000 |最大蒙特卡洛样本数| | SPACE_TRACK_MAX_MC_TOTAL_STEPS |没有| 10000000 |最大样本数×时间步长×卫星数| | SPACE_TRACK_MAX_TLE_HORIZON_DAYS_WARN |没有| 7 |当TLE传播超过这么多天时发出警告| | MCP_HOST |没有| 127.0.0.1 |绑定主机| | MCP_PORT |没有| 8000 |绑定端口| | MCP_PATH |没有| /mcp |可流式传输的HTTP路径|
凭据和Cookie永远不会被记录。
跑
export SPACE_TRACK_IDENTITY=your_username
export SPACE_TRACK_PASSWORD=your_password
space-track-mcp或者：
python -m space_track_mcp.server服务器侦听 http://127.0.0.1:8000/mcp （流式HTTP）。使用支持Streamable HTTP的MCP客户端进行连接。
速率限制
- 硬限制： 每分钟30个请求、每小时300个请求（令牌桶式）。
- 课堂指导： GP~1/小时；SATCAT/SATAT_DEBUT~1/UTC 1700后的一天；gphistory需要窄过滤器或显式过滤器
ack_heavy_query=true.
超过限制时，服务器返回一个明确的错误 retry_after_seconds.使用 spacetrack_rate_limit_status 检查当前状态。
工具
| 工具 | 说明 |
|---|---|
spacetrack_query | 通用查询：任何控制器/类、谓词字典、格式（json/tle/csv/…）、可选的limit/orderby/stream。 |
spacetrack_get_predicates | 类的Modeldef：谓词列表（名称、类型、可空、默认值）；缓存。 |
spacetrack_gp_latest | NORAD ID的最新GP元素；格式为tle/json/csv/kvn/xml。更喜欢传统的TLE类。 |
spacetrack_positions_over_time | 获取给定NORAD ID的TLE，使用SGP4传播，返回随时间变化的位置（和速度）的JSON。 输入： norad_cat_ids，可选 num_points （默认值3）， step_minutes （默认值为60）。输出： satellites[] 随着 object_name, norad_cat_id, positions[] 每个 {time, position_km, velocity_km_s} （ECI，公里）。 |
spacetrack_satcat_daily | SATCAT快照（最佳做法：~1/天）。 |
spacetrack_satcat_debut_since | SATCAT_DEBUT自N天以来发生了变化（例如，DEBUT/>now-1/）。 |
spacetrack_cdm_public_recent | 公共CDM（例如，自过去8小时以来）。 |
spacetrack_rate_limit_status | 电流限制器状态（令牌剩余，下一次重置）。 |
| 轨道投影 | |
orbit_propagate | TLE或状态的确定性传播。输入：卫星\[\]、结束时间或持续时间秒、步长秒、帧输出（ECI/ECEF/LLA）、传播器（sgp4/数值）、数值模型（重力、阻力）。 |
orbit_propagate_monte_carlo | 具有state_sigma或state_covariance的N个样本；返回每个时间步长的平均值+p50/p90/p95/p99半径包络。输入：带有TLE或状态的卫星\[\]。 |
orbit_propagate_monte_carlo_by_norad | 更简单： 通过 norad_cat_ids （例如\[255443013\]）；获取TLE，运行MC。选项与orbit_prospace_monte_carlo相同。 |
orbit_propagate_monte_carlo_proximity | MC用于多颗卫星+成对距离统计。输入：norad_cat_ids（≥2）。集 include_satellite_ephemeris=true 用于完整星历表（默认：仅成对，输出较小）。 |
spacetrack_project_positions | 一个调用：获取NORAD ID的GP/TLE，然后传播（如果启用了monte_carlo，则运行MC）。 |
orbit_fit_state_from_points | 从3+个状态向量中，估计状态和可选的6×6协方差（第2阶段）。 |
eph_read | 解析.eph（特殊扰动）星历文件；标头+状态向量。 |
eph_to_orbit_state | 从.eph中提取一个状态 orbit_propagate. |
satellite_analyze | 北美防空司令部任务和活动推断： 获取TLE历史，推导轨道状态、机动、SSO/GEO行为、重访、可选接近、任务评分和基础总结。 |
| TLE分析 | |
tle_history | NORAD ID的标准化历史TLE数据 |
tle_quality | 目录质量：纪元间隙、拟合稳定性、元素噪声、更新节奏。 |
tle_residuals | 元素变化残差；将机动与目录噪声区分开来。 |
tle_credibility | PRD v2： TLE可信度（跟踪_质量，解释_可靠性）。 |
| 机动 | |
maneuver_detect | 从轨道要素变化中检测候选机动。 |
maneuver_classify | 根据Δn、Δa、Δi、Δe对机动类型进行分类。 |
| RPO/接近度 | |
rpo_scan | 在类似的轨道状态下搜索附近的物体。 |
rpo_timeline | 两个物体随时间的成对距离。 |
rpo_assessment | 近距离接近的假设（重合、星座、检查、交会）。 |
| 轨道行为 | |
orbit_regime | 分类制度：VLEO/LEO/MEO/GEO/HEO+SSO。 |
orbit_revisit | 重复周期、覆盖频带、ROI通过频率。 |
orbit_geo_behavior | GEO经度、漂移率、定位框。 |
| 地理的 | |
geo_groundtrack | 地面轨道路径（随时间变化的纬度/经度）。 |
geo_overflight | 经过一个地理区域。 |
geo_localtime | SSO的当地太阳时（LTAN）。 |
| 目录/关系 | |
catalog_neighbors | 具有相似轨道参数的物体。 |
catalog_cluster_tool | 将卫星组合成飞机。 |
catalog_family_tool | 可能的家庭分裂。 |
constellation_detect | 瑞安的DBSCAN；检测星座成员资格。 |
| 事件调查 | |
event_breakup_suspect_tool | 检测可能的碎片事件。 |
event_decay_analysis_tool | 大气阻力衰减，再入趋势。 |
event_track_gap_tool | 解释追踪失踪。 |
| 事件管理 | |
case_create | 创建调查案例。 |
case_list | 列出所有案例。 |
case_add_object | 将卫星添加到机箱中。 |
case_add_note | 添加分析师/代理人备注。 |
case_hypothesis | 添加假设和预期可观测值。 |
case_timeline | 合并时间线（TLE、机动、笔记）。 |
case_export | 导出报告（markdown或JSON）。 |
示例（GP TLE用于ISS）
相当于：
/basicspacedata/query/class/gp/norad_cat_id/25544/format/tle
使用工具：
- spacettrack_query：
class_name="gp",predicates={"norad_cat_id": 25544},format="tle". - spacettrack_gp_lextress：
norad_cat_id=25544,format="tle".
获取两颗卫星随时间的坐标
太空轨道返回 轨道要素 （TLE/GP），而不是预先计算的位置。得到 坐标随时间变化 你：
- 获取两颗卫星
- 选择两个NORAD ID（例如ISS= 25544，另一个= 48274)，或 - 使用 空间轨迹查询: class_name="satcat", format="json", limit=2 获取两个目录条目并阅读它们 NORAD_CAT_ID.
- 获取他们的元素
- spacettrack_gp_lextress: norad_cat_id=[25544, 48274], format="tle" - 或 空间轨迹查询: class_name="gp", predicates={"norad_cat_id": [25544, 48274], "decay_date": "null-val", "epoch": ">now-10"}, format="tle".
- 将元素转换为坐标\
将TLE传播到你关心的时代 SGP4 （例如Python sgp4).MCP不运行传播；您可以在本地或脚本中执行该操作。
示例脚本 （使用与MCP相同的凭据，不需要MCP客户端）：
pip install sgp4
python examples/two_satellites_coordinates.py
# Or with two NORAD IDs:
python examples/two_satellites_coordinates.py 25544 48274该脚本从Space Track获取TLE，并打印当前+1小时、+2小时的ECI位置（公里）。对于lat/lon/alt，您需要转换ECI→ ECEF → 大地测量（例如 sgp4.conveniences 或 pymap3d).
仅使用MCP（例如在光标中）：\ 让AI打电话 spacettrack_gp_lextress 具有两个NORAD ID和 format="tle"。你会得到TLE文本。要在特定时间获取坐标，请将本地SGP4步骤（或上面的脚本）与TLE一起使用。
轨道传播、框架和蒙特卡洛不确定性
框架和惯例
- TLE/SGP4帧：所有SGP4传播都在 主题 帧（真赤道、均点）。你看到的任何地方：
- mean_position_km / position_km_ECI 和 mean_velocity_km_s / velocity_km_s_ECI，这些是 ECI团队 矢量单位为km和km/s。
- ECEF:
- position_km_ECEF / mean_position_km_ECEF 使用a进行转换 基于GMST的地球自转: - earth_rotation_model = "GMST (IAU 1982-style)" - ecef_frame = "ITRF-like" （近似地球固定框架）。
- LLA:
- lat_deg, lon_deg, alt_km 大地坐标是否在 世界大地测量系统84 (lla_datum = "WGS84").
这些惯例在 metadata 对于确定性(orbit_propagate)蒙特卡洛(orbit_propagate_monte_carlo)输出。
spacetrack_project_positions：默认值和蒙特卡洛
spacetrack_project_positions 是一种一键式工具，用于：
- 从Space Track获取给定的最新GP/TLE
norad_cat_ids - 使用SGP4+本地帧转换向前传播。
- 返回：
- A. 蒙特卡洛总结 （默认），或 - A. 确定性轨迹 （如有要求）。
默认值（当您仅通过时 norad_cat_id):
- 传播时间：6小时（~19个点，20分钟步长）。
- 框架：
frames_out = ["ECI", "ECEF", "LLA"]（在LLA要求时添加了ECEF）。 - 默认情况下启用蒙特卡洛:
- samples = 200 - uncertainty = { state_sigma: { pos_km: [0.2, 0.2, 0.2], vel_km_s: [0.0002, 0.0002, 0.0002] } }
到 关闭蒙特卡洛 并得到一条确定性路径，pass：
{
"norad_cat_id": 25544,
"monte_carlo": { "enabled": false }
}蒙特卡罗不确定性是如何表示的
对于每个卫星和每个时间步长， orbit_propagate_monte_carlo 产生a 总结 进入：
- 平均状态:
- mean_position_km （TEME ECI，公里） - mean_velocity_km_s （TEME ECI，公里/秒） - 可选的 mean_position_km_ECEF 和 lat_deg, lon_deg, alt_km.
- 标量不确定性（与平均值的距离）:
- p50_radius_km：50%的样本位于平均值的半径范围内。 - p90_radius_km：90%的样本位于该半径范围内。 - p95_radius_km95%的样本位于该半径范围内。 - p99_radius_km99%的样本位于该半径范围内。
这些半径给你一个 概率包络 围绕平均轨迹：较小的半径=较高的置信度；半径越大=色散越大。
RTN（径向/沿轨道/交叉轨道）分解
为了使误差条在视觉上有意义，蒙特卡洛引擎还分解了 快速组织坏死 每次帧：
p95_radial_km:
- 绝对值的第95百分位数 径向的 偏差（沿地球中心半径的进出）。
p95_along_track_km:
- 绝对值的第95百分位数 沿轨 偏离（沿轨道前进/后退）。
p95_cross_track_km:
- 绝对值的第95百分位数 跨轨 偏离（轨道平面外）。
pos_cov_rtn_km2:
- RTN位置偏移的3×3协方差矩阵，单位为km²。
例子
| 示例 | 说明 |
|---|---|
examples/satellite-classification-viz.html | SDA仪表板：NORAD下拉菜单、分析、蒙特卡洛投影。跑 python examples/serve_classification.py，打开http://127.0.0.1:8765 |
examples/tri-sat-distances-heatmap.html | 多卫星蒙特卡罗邻近距离时间序列图。从以下位置加载JSON orbit_propagate_monte_carlo_proximity. |
examples/readme_eph.md | .eph文件格式和MCP工具 eph_read, eph_to_orbit_state. |
examples/generate_eph.py | 生成用于测试的合成.eph文件。 |
许可证
请参阅存储库许可证。