MCP

适合：第一次把紫微接进对话的人。不用装库，不用写代码。

Cursor 与 Claude 先装插件。插件里的 Skill 会先调用 chart / to_text，再解释。ChatGPT 在 B. 连接器 里导入插件市场。其余客户端填同一个地址，并贴上 C. 没有 Skill 时 的说明。

本地 stdio 用不上：这是公开的 HTTP，没有要启动的命令。名字、必填字段和返回形状写在这一页的后半。

A. 装插件

Cursor 与 Claude 先装插件。插件带上 Skill，Skill 会先调用 chart 或 to_text，再解释。

Claude Code

这是今天的用户安装。

claude plugin install ziwei --marketplace x-haose/x-ziwei

插件里的 .mcp.json 使用 type: http（Claude Code 也接受别名 streamable-http）。无鉴权。组件都在插件根目录，不放进 .claude-plugin/。

Cursor

使用者的步骤是安装、重载、用自然语言问，全程不用终端。

官方 Marketplace 尚未提交，现在不能在商店里点安装。不要把下面的步骤当成今天就能在商店里完成。商店上架之后，从 Marketplace 一键安装即可。

Team / Enterprise 今天可以走仓库导入，这仍不是公开商店：Dashboard → Plugins & MCPs → Import，由管理员从 x-ziwei 仓库导入。成员在 Cursor 里启用该插件。

B. 连接器

ChatGPT 从插件市场导入，步骤在下面。没有插件壳的客户端，把同一个公网地址填进连接器。这些连接不带本仓库的 Skill，装上之后把 C 的说明贴进系统提示或自定义说明。

下面只写当前文档里能核对的入口。没有官方插件壳的产品，不要当成已经上架。

ChatGPT

今天的安装：插件 → 添加 → 添加插件市场。来源填 GitHub 仓库，授权后导入市场，再安装 ziwei。公开插件目录的上架还没就绪。

同一个 添加 菜单里，三项各做各的：

• 添加插件市场：从 GitHub 导入市场。安装 ziwei 走这里。
• 创建插件：新建一个插件包。用户安装 ziwei 不点这项。
• 录制技能：把一次操作录成技能。这项不安装 MCP。

官方步骤写的是工作区管理员：管理控制台 → 插件 → 添加 → 导入插件市场，字段是来源和路径，确认按钮也叫导入插件市场。个人客户端菜单上的字是「添加插件市场」。这两张表单的字段是否一致，待真机确认。见从 GitHub 导入和同步插件市场（中文）。

Grok

网页打开 grok.com/connectors，New Connector → Custom，URL 填 https://ziwei.x-haose.com/mcp。本服务无鉴权；对话框若要求认证，留空或不做 OAuth。Grok Business / Enterprise 要先由团队管理员在控制台加连接器，成员才能用。见 Connectors。

Grok Build 也可以写进配置。命令会记到 ~/.grok/config.toml：

grok mcp add --transport http ziwei https://ziwei.x-haose.com/mcp

或手写：

[mcp_servers.ziwei]
url = "https://ziwei.x-haose.com/mcp"

见 MCP Servers。装上之后同样贴 C 的说明。

Codex

Codex 的 Streamable HTTP 条目在 ~/.codex/config.toml（受信任的项目也可用项目里的 .codex/config.toml）。ChatGPT 桌面端、Codex CLI、IDE 扩展共用这份配置。

[mcp_servers.ziwei]
url = "https://ziwei.x-haose.com/mcp"

等价命令：

codex mcp add ziwei --url https://ziwei.x-haose.com/mcp

不要加 bearer token，也不要跑 codex mcp login。没有任何凭证来源时，Codex 可以无认证连接。桌面端或 IDE 里选 Streamable HTTP，URL 填同一地址。见 Model Context Protocol。

OpenAI Agents SDK 走 Responses 托管调用时，用 HostedMCPTool，server_url 为 https://ziwei.x-haose.com/mcp。进程内自己连则用 MCPServerStreamableHttp，params["url"] 为同一地址。两种都不要附带 Authorization。

C. 没有 Skill 时

能填远程 MCP URL 的客户端，地址都是 https://ziwei.x-haose.com/mcp，不要加认证头。没有 Skill 通道时，把下面其中一段贴进系统提示或自定义说明。规则与插件 Skill 相同。

中文

你是紫微斗数解读助手。公网 MCP 只有 https://ziwei.x-haose.com/mcp，工具只有 chart 与 to_text。

硬规则：
- 禁止凭记忆编造命盘、星曜、四化或大限。没有工具结果就没有盘。
- 先调用 chart 和/或 to_text，再用人话解释。
- 不要发明第三个工具，没有 lookup。
- 解释属于你。引擎只排盘，盘面与 iztro 金标对齐。不要改写成另一套星曜。
- 工具失败就说明错误，不要补假盘，也不要猜时辰。

阳历最短入参（chart 与 to_text 相同）：calendar=solar，date=YYYY-M-D，timeIndex=0-12，gender=male 或 female。
时辰不明先问。农历必须另给 leap：notLeap、leap 或 leapFixed。
要盘面用 chart；要 Markdown 用 to_text。运限时 chart 同时给 targetDate 与 targetTimeIndex；to_text 设 includeHoroscope=true 并带同样的目标日、时。

English

You interpret Zi Wei Dou Shu charts. The only MCP endpoint is https://ziwei.x-haose.com/mcp. The only tools are chart and to_text.

Rules:
- Never invent a chart, star placement, mutagen, or decade from memory. No tool result means no chart.
- Always call chart and/or to_text first, then interpret in plain language.
- Do not invent a third tool. There is no lookup.
- Interpretation belongs to you. The engine only casts the chart and is gold-aligned with iztro. Do not rewrite the result into a different set of stars.
- If a tool fails, say so. Do not fill in a fake chart, and do not guess the hour.

Solar minimum for both tools: calendar=solar, date=YYYY-M-D, timeIndex=0-12, gender=male or female.
Ask when the hour is unknown. Lunar dates also require leap: notLeap, leap, or leapFixed.
Use chart for the structured chart and to_text for Markdown. For a horoscope, pass targetDate and targetTimeIndex to chart; set includeHoroscope=true on to_text with the same target date and hour.

兼容 / 调试

手贴 JSON 只接上 URL，不带 Skill。有插件时走 A。这里是插件没装上、或客户端只有一份配置文件时的形状。

Cursor 用户级写在 ~/.cursor/mcp.json，只给当前项目用就写在项目里的 .cursor/mcp.json。插件内部的 mcp.json 也是这一份：

{
  "mcpServers": {
    "ziwei": {
      "url": "https://ziwei.x-haose.com/mcp"
    }
  }
}

Claude 比 Cursor 多一个 "type": "http"。Claude Code 写在项目根目录的 .mcp.json，或写进用户配置里的 mcpServers。桌面端和 claude.ai 的自定义连接器要 JSON 时，用同一份：

{
  "mcpServers": {
    "ziwei": {
      "type": "http",
      "url": "https://ziwei.x-haose.com/mcp"
    }
  }
}

Cascade（Windsurf / Devin Desktop）的远程 HTTP 条目用 serverUrl。在 MCP 菜单里打开配置文件再写入。当前 Devin 文档的默认路径是 ~/.config/devin/mcp_config.json（设置了 XDG_CONFIG_HOME 时走该目录）：

{
  "mcpServers": {
    "ziwei": {
      "serverUrl": "https://ziwei.x-haose.com/mcp"
    }
  }
}

已经有别的服务器时，只把 "ziwei" 这一段合并进去，不要整份覆盖。本地 stdio MCP 用不上。

装上之后怎么说

不必背参数名。用白话说，模型自己去填。装了插件时，也可以直接说「阳历 2000-8-16 寅时女命，排紫微盘」。回答前必须先调用工具。

第一句排出 2000 年 8 月 16 日、寅时、女性的本命盘。寅时是时辰索引 2（03:00–05:00），模型会自己换算。

第二句让模型去取这张盘的 Markdown，再据此用白话讲。to_text 交出来的是盘面事实（默认带知识包释义），不是已经写好的「事业如何」。话是模型说的，数是工具算的。

两句可以分两次说，也可以写在同一条消息里。

已冻的契约

工具只有这两个。下面的必填字段和返回键是可以钉死的部分：以后可以加可选字段，不会改名、不会删掉这些键。

公历最短的一次入参，对应「帮我排个盘：公历 2000-8-16，寅时，女」：

{
  "calendar": "solar",
  "date": "2000-8-16",
  "timeIndex": 2,
  "gender": "female"
}

两个工具共用这一组出生参数：

默认盘面语言是简体中文。给模型喂中文盘，比喂英文意译星名更稳，见让 AI 解读命盘。

chart

星盘 JSON。返回 { "astrolabe": { ... } }，键与 x-iztro 的 to_dto() 对齐，契约键是语言无关的 *_key。

要运限时再加上目标日期，两个一起给，返回里才多出 horoscope：

to_text

同一组出生参数，返回 { "text": "..." }。text 是 Markdown，不是 astrolabe_to_prompt 那种带指令的提示词。格式见语义化文本。

时辰

timeIndex 不是钟点。子时拆成首尾两段，所以是 0–12 共 13 个值。

它不做什么

• 不写命理结论。to_text 是盘面文字，解读是模型在读完这段文字之后的事。
• 不接受模型自己安星、自己推干支。
• 不替代把库嵌进你自己的产品。那条路仍是装 Rust / Python / Go，见快速开始和让 AI 解读命盘。