MCP Darksky

mcp darksky

以结构化分数返还韩国夜空拍摄条件的MCP服务器。

该项目的目标不是单纯地回答“今天能看到星星吗？”，而是同时计算云、月光、空气质量、结露风险、光解、目标高度和各时间段的流动，以AI可以直接用于实际出师判断的形式返回结果。

/install 页面是一个轻松的用户指南和GPT应用程序连接登录页面。与MCP、API、部署和数据相关的开发人员信息可与此README docs/hosting-and-data-sources.md收藏在中。

快速入门

1.安装依赖性

npm install

2.运行本地MCP

npm start

3.运行HTTP服务器

npm run start:railway

这个MCP能做的事

• 判断今晚是否可以出师
• 确定几点到几点最好
• 根据广角银河、广角夜景、宽带deep-sky、narrowband deep-sky、star trail的不同用途，对同一个夜晚的解释不同
• 确认结露危险、月光干扰、可吸入颗粒物/气溶胶、风等扣分因素
• 按地点名称直接查询
• 确认韩国标准推测的Bortle-like光解值
• 较远的日期不会有过高的精度。 outlook 模式摘要

是为了谁的项目

普通用户和新手

例如，回答这样的问题。

• 내일 밤 안반데기에서 은하수 찍기 괜찮아?
• 오늘 서울 근교에서 출사 가도 돼?
• 몇 시가 제일 좋아?

在这种情况下，AI可以读取MCP结果并解释如下：

• 今晚是不是值得一去的夜晚
• 最好的时间段是什么时候。
• 降低分数的主要原因是什么
• 对于初学者来说是否也可以

熟练者

例如，它适合这种用途。

• 广角银河/广角夜景/宽带deep-sky/narrowband deep-sky/star trail比较
• 确认目标高度和moon separation
• 确认各时间段的score curve
• 不是整个晚上，而是判断“什么时候最好”

公共端点策略

您可以安全地将此存储库中介绍的公共地址视为用于个人评估和轻松的交互式测试。

• 公共端点可能有rate limit、更改或中断。
• 不保证可用性、吞吐量、长期兼容性和操作支持。
• 如果您计划重复呼叫、自动化、团队共享、产品集成和广泛使用，建议直接部署公开地址，而不是原封不动地写。

由于可能有基于当前maintainer运营的基础架构和成本结构的地址，因此在实际使用阶段，最好将转移到您的基础架构的前提放在README中。

Self-hosting指南

如果符合下列条件之一，建议直接托管：

• 如果您想继续与其他人共享
• 如果存在自动化或重复调用工作负载
• 要集成到产品、服务和内部工具中：
• 需要自行管理使用情况和成本

直接托管时，请使用您的基础设施和您的API密钥。

建议的顺序如下：

1. 首先在本地验证Node HTTP服务器。
2. 直接设置所需的环境变量。
3. 准备估计光解所需的runtime artifact和本地数据。
4. 测试通过后分发。

第三方服务和数据

该项目可以同时使用外部天气、地理编码和卫星夜间照度数据。

• 开放天气
• Kakao当地API
• NASA Black Marble系列数据

此存储库不解释或保证外部提供程序的策略。用户必须亲自查看并遵守每个提供程序的条款、配额、来源标记要求和许可使用范围。

特别推荐以下原则：

• 不要大范围地重新部署公共演示地址，实际利用率以直接托管为准
• 自己发放Kakao API密钥并管理安全设置
• 数据来源将如实显示，但不要写成第三方批准或保证该项目。

相关清理文档包括： docs/hosting-and-data-sources.md单独放在了。

无背书

README和代码中提到的外部服务或数据提供程序名称用于说明。这并不意味着该提供商将批准、赞助或担保该项目。

主要结果字段

综合分数

• overall_score
• cloud_score
• transparency_score
• darkness_score
• dew_risk_score
• stability_score
• mode_score

时区流

• score_curve
• blocker_timeline
• window_rankings
• curve_summary

也就是说，这个MCP不把整个晚上看成一个分数，而是按时间段一起返回什么时候变好，什么时候变坏。

派生判断

• best_window
• mode_best_window
• mode_ready
• confidence

天文相关

• 天文博明/天文夜计算
• 月亮高度/月亮照度/月亮干涉
• 银河中心可见性
• 目标高度/airmass
• 月球目标分离

光解推定

根据本地Black Marble数据计算以下值：

• estimated_bortle_center
• estimated_bortle_range
• estimated_bortle_band
• equivalent_zenith_brightness_mpsas
• 韩国内亮度/暗percentile

输入方式

1.输入坐标

• latitude
• longitude

2.输入地点名称

• place_query

示例：

• 안반데기마을
• 육백마지기
• 구룡령

输入地点名称使用Kakao Local API转换为坐标。

3.输入选择

• site_profile.bortle_class
• site_profile.elevation_m
• site_profile.near_water
• mode
• target

拍摄模式

• general
• wide_field_milky_way
• wide_field_nightscape
• broadband_deep_sky
• narrowband_deep_sky
• star_trail

也就是说即使是同一个晚上 광각 은하수에는 좋지만 broadband deep-sky에는 애매하다 可以进行同样的解释。

MCP工具

score_night_sky

最近日期的详细评分工具。

• 各时间段的分数
• 最佳时间
• 危险因素
• 模式适应性
• 目标天文信息

同时返回。

score_night_sky_outlook

用于较远日期的汇总展望工具。

+6일 이후返回coarse outlook，而不是显示过于精确的时区分数。

estimate_light_pollution

返回光解和Bortle-like估计结果。

describe_light_pollution_method

描述光解估计方法和假设。

describe_scoring_model

描述分数字段和分析规则。

score_night_sky_via_link

返回共享链接，如安装页面、JSON API和MCP地址。

端点

• /mcp：MCP连接
• /api/score：详细评分API
• /api/score-outlook：用于较远日期的outlook API
• /api/light-pollution：光解推测API
• /api/light-pollution/method：方法API
• /prompt：无MCP设置的提示页面
• /prompt.txt：plain text提示符
• /install：简单的安装指南和GPT应用程序连接页面
• /health：健康检查

日期策略

该项目使用“越远的日期越保守”的原则。

• 0~5일：使用详细分数
• 6~15일: outlook 引导到路径

原因是，如果在较远的日期原封不动地给出各时间段的分数和包括空气质量、月光和光解分析在内的结果，false precision就会增大。

处理外部API故障

Open-Meteo和Kakao Local API调用 초기 1회 + 재시도 최대 3회 作为策略操作。

也就是说，暂时的5xx或429系列问题会在不立即处理失败的情况下进行简短的重试，如果失败，则会显式返回错误。

环境变量

• PORT 或 MCP_PORT：Node HTTP端口
• HOST：Node HTTP bind host，默认值 0.0.0.0
• PUBLIC_BASE_URL：外部可见的服务默认URL
• KAKAO_REST_API_KEY: place_query 使用时需要
• REST_API_KEY：用于本地兼容的alias
• BLACK_MARBLE_RUNTIME_ARTIFACT_PATH：覆盖runtime artifact路径
• BLACK_MARBLE_RUNTIME_ARTIFACT_URL：在Railway引导时下载runtime artifact URL
• ALLOWED_HOSTS：Node HTTP允许主机列表

注意：

• 像Railway一样 PORT在自动授予的环境中 npm start自动进入HTTP服务器模式。

本地数据

要直接在服务器上处理光解估计，需要以下本地数据：

• data/VNP46A4/...
• data/VJ146A4/...
• data/black-marble-korea-runtime.npz
• data/black-marble-korea-distribution.json

由于原始瓷砖的容量很大，通常最好不要包含在Git存储库本身中。

开发

npm install
npm test

部署前核对表

1. 设置环境变量。

- PUBLIC_BASE_URL - KAKAO_REST_API_KEY - 必要时 ALLOWED_HOSTS

1. 验证本地数据是否存在。

- data/black-marble-korea-runtime.npz - 需要时raw tile和distribution文件

1. 运行测试。

- npm test

1. 检查缺省行为。

- /health - /api/score - /api/score-outlook - /mcp

1. 验证用户链接。

- /install

建议的部署方式

按照目前的结构标准 Railway 首先推荐相同的Node容器实例。

原因：

• 非常适合Node服务器流
• 易于同时处理Python光解估计和本地文件结构
• 便于操作员理解和维护结构

为了减少贡献混乱，当前存储库仅基于基于Railway的Node HTTP部署。