AstroWay MCP 是 AstroWay Calculation API 的官方 MCP 服务器，面向 Claude Desktop、Cursor、Windsurf 以及任何兼容 MCP 的 AI 智能体，把占星相关计算端点暴露为可直接调用的工具。
用途 它让 AI 客户端能够直接调用占星计算能力，包括本命盘、合盘（synastry）、行运（transits）、吠陀 Dasha（Vimshottari、Yogini、Ashtottari、Kalachakra）、16 种 Vargas、塔罗（Rider-Waite / Marseille / Lenormand）、数字命理（5 种体系）、人类图、AI 星座运势等。
主要能力
- 工具由构建时脚本读取生产 API 的规范端点清单自动生成，按输入形态分类（chart、twoChart、chartTarget、horoscopeSign、year、date、generic），并生成带类型的工具定义，注册为带 Zod 输入 schema 的 MCP Tool。API 新增端点后，下一次 MCP 版本会自动包含，无需手动同步工具定义。
- 支持子集注册：通过 ASTROWAY_TOOL_GROUPS 只注册部分工具组，常见分组有 western、vedic、tarot、numerology、hd（人类图）、relational（合盘/composite/davison）、prognostics（行运/推运/回归）、aspects、horary、geo、chinese、bazi、mayan、iching、runes、geomancy。可用 npx @astroway/mcp --list-tools 查看完整工具集。
- ASTROWAY_READONLY=1 会跳过三个内部调用 LLM 的分组（ai、horoscope、reports），适合只做确定性星盘计算、不消耗文本生成额度的场景。
- 发现（精简）模式：设置 ASTROWAY_DISCOVERY_MODE=1 后，不再预先注册 600+ 工具，而是只暴露两个元工具：astroway_find_tool(query, limit?) 用于关键词搜索整个目录并返回最匹配工具及其一行描述和输入参数名；astroway_call_tool(name, arguments?) 用于调用搜索到的任意工具。代价是经 astroway_call_tool 分发的调用只返回文本结果，无法携带直接注册工具所提供的、经校验的 structuredContent。发现模式会取代 ASTROWAY_TOOL_GROUPS / ASTROWAY_READONLY。
- 目录在会话期间冻结：工具、提示和资源都打包在已发布的 npm 包中，运行时不变。工具标识在同一主版本内稳定，输入形态在同一次版本内稳定；跨主版本升级的破坏性变更会公告，并提供 MCP_FLAT_TOOLS=1 作为过渡。重新安装（npm i -g @astroway/mcp@latest 或 npx -y @astroway/mcp）可刷新目录。
使用方式 在 macOS 的 ~/Library/Application Support/Claude/claude_desktop_config.json 或 Windows 的 %APPDATA%\Claude\claude_desktop_config.json 中添加配置，重启 Claude Desktop 后，astroway 服务器会出现在聊天输入框底部的 MCP 指示器中。Cursor 可添加到 ~/.cursor/mcp.json。Cline / Continue / Windsurf / Copilot / VS Code MCP 等客户端同样使用 npx @astroway/mcp 命令，放入各自的 MCP 配置文件即可。也可作为 stdio 服务器运行。
验证安装：重启 MCP 客户端后打开 MCP 指示器，应看到 astroway 列为活动服务器，悬停或点击可显示注册的工具、提示和资源数量；npx @astroway/mcp --list-tools 可打印当前版本完整工具列表。首次冷启动约需 2-3 秒（Node + 到 api.astroway.info 的 TLS 握手）。终端可用 npx @astroway/mcp --version 查看版本，npx @astroway/mcp --list-tools synastry 查看匹配工具。若服务器未出现，可在 env 中设置 LOG_LEVEL=debug 并重启，启动行和错误会出现在客户端的 MCP 调试面板。
示例提示词包括：计算指定出生时间地点的本命盘并识别太阳、月亮、上升和紧密相位；比较两张星盘的最强跨相位；运行 Vimshottari Mahadasha 并判断当前所处行星周期；查询指定日期命中本命盘的主要外行星行运；用 Rider-Waite 牌阵抽取三张过去-现在-未来牌并指定 seed；查询人类图类型、策略、权威、已定义中心和化身十字；使用 astroway_mcp_ai_chat 询问土星位置含义并要求引用宫位和相位容许度。
适用场景 适合需要在 AI 客户端中进行占星、吠陀占星、塔罗、数字命理、人类图等计算的用户，以及希望以 MCP 方式把占星计算接入自有智能体的开发者。
限制与说明 该 MCP 服务器不上报遥测、分析或使用数据，唯一的网络流量是用户请求的 AstroWay API 调用，直接由本机发往 https://api.astroway.info/v1。出站请求带两个标识头：User-Agent: astroway-mcp/<version> (Node/<node-version>) 和 X-Astroway-Channel: mcp，均不含会话 ID、机器指纹或个人信息。
使用需在 https://api.astroway.info/dashboard/sign-up 注册，免费提供每月 10 000 credits，无需信用卡；每次请求消耗 5–500 credits，取决于端点。本地测试可使用沙箱密钥（aw_test_...），免费返回确定性响应。常见错误：401 表示 API 密钥缺失、无效或已撤销；402 表示免费额度用尽；422 表示请求体字段校验失败。
本仓库是 @astroway/mcp 的公开展示页（README、CHANGELOG、LICENSE、安装说明），可运行代码即已发布的 npm 包，源码维护在私有 AstroWay monorepo 中，生成的包以 MIT 许可开源并随每次发布上线 npm。
