# MCP (/zh/docs/guide/mcp)

紫微斗数的公开 MCP，所有客户端共用一个地址。



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

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

<Callout title="地址与保证">
  * 地址：`https://ziwei.x-haose.com/mcp`。Streamable HTTP，无鉴权。
  * `chart` 与 `to_text` 已冻结，与 iztro v2.6.1 逐字段对齐。716,314 例金标，允许的差异是 0。这是复现口径，不是流派裁决。见[准确性保证](/zh/docs/guide/about/accuracy)。
</Callout>

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

<Callout title="浏览器打开它看不到文章">
  `/mcp` 是给客户端连的端点，不是文档页。要读的是这一页；要复制的是上面的地址。
</Callout>

## A. 装插件 [#a-装插件]

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

<Callout title="Skill 强制先调工具">
  Skill 与 [x-ziwei](https://github.com/x-haose/x-ziwei) 里的 `plugin/shared/skills/ziwei/SKILL.md` 相同。没有工具结果就没有盘。先调 `chart` 和/或 `to_text`，再用人话解释。不要发明第三个工具，没有 `lookup`。工具失败就说明错误，不要补假盘，也不要猜时辰。
</Callout>

### Claude Code [#claude-code]

**这是今天的用户安装。**

```bash title="Claude"
claude plugin install ziwei --marketplace x-haose/x-ziwei
```

<Steps>
  <Step>
    运行上面的命令。在会话里也可以先 

    `/plugin marketplace add x-haose/x-ziwei`

    ，再 

    `/plugin install ziwei@x-ziwei`

    。
  </Step>

  <Step>
    用自然语言问一次排盘。回答前会先调用 

    `chart`

     或 

    `to_text`

    。
  </Step>

  <Step>
    工具列表里应能看到 

    `chart`

     和 

    `to_text`

    ，没有第三个。
  </Step>
</Steps>

<Accordions>
  <Accordion title="贡献者：仅 --plugin-dir 自测">
    在 [x-ziwei](https://github.com/x-haose/x-ziwei) 仓库里直接加载，不经过市场。这只给贡献者自测：

    ```bash title="Claude"
    claude --plugin-dir ./plugin/claude
    ```
  </Accordion>
</Accordions>

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

### Cursor [#cursor]

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

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

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

<Steps>
  <Step>
    安装插件。Team / Enterprise 用上面的仓库导入；商店上架之后，在 Marketplace 一键安装。
  </Step>

  <Step>
    重载窗口（Developer: Reload Window）。
  </Step>

  <Step>
    用自然语言问一次，例如「阳历 2000-8-16 寅时女命，排紫微盘」。回答前会先调用 

    `chart`

     或 

    `to_text`

    。
  </Step>
</Steps>

<Accordions>
  <Accordion title="贡献者 / 未上架时自测">
    个人环境在商店上架前，只能把插件拷进本地目录。这不是使用者的安装步骤。在 [x-ziwei](https://github.com/x-haose/x-ziwei) 仓库根目录执行，拷贝进本地插件目录，不要指到仓库外的符号链接：

    ```bash title="Cursor"
    mkdir -p ~/.cursor/plugins/local
    rm -rf ~/.cursor/plugins/local/ziwei
    cp -a plugin/cursor ~/.cursor/plugins/local/ziwei
    ```

    安装目录必须自带 `skills/ziwei/SKILL.md`，Cursor 不接受跳出插件根目录的路径。拷贝后重载窗口，在 Customize 里确认插件 `ziwei`、技能，以及 MCP `https://ziwei.x-haose.com/mcp`。

    Team / Enterprise 若关闭了 Allow Local Plugin Imports，这个目录不会被加载。同名市场插件已安装时，市场安装优先于本地副本。
  </Accordion>
</Accordions>

## B. 连接器 [#b-连接器]

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

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

### ChatGPT [#chatgpt]

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

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

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

<Steps>
  <Step>
    打开插件，点添加，选添加插件市场。
  </Step>

  <Step>
    官方管理员表单：来源填 

    `https://github.com/x-haose/x-ziwei`

    ，路径留空。仓库根目录已有 

    `.claude-plugin/marketplace.json`

    。Codex 与 ChatGPT 还会找 

    `.agents/plugins/marketplace.json`

    ，仓库正在补这个文件。不要填清单文件名。分支、标签或提交留空，用默认分支。
  </Step>

  <Step>
    授权 GitHub，导入市场。
  </Step>

  <Step>
    导入完成后安装 

    `ziwei`

    。对话里输入 

    `@`

     选用。
  </Step>
</Steps>

官方步骤写的是工作区管理员：管理控制台 → 插件 → 添加 → **导入插件市场**，字段是**来源**和**路径**，确认按钮也叫**导入插件市场**。个人客户端菜单上的字是「添加插件市场」。这两张表单的字段是否一致，待真机确认。见[从 GitHub 导入和同步插件市场](https://help.openai.com/en/articles/20001504-importing-and-syncing-plugin-marketplaces-from-github)（[中文](https://help.openai.com/zh-hans-cn/articles/20001504)）。

<Callout type="warn" title="网页端要另验">
  官方说明：导入的插件若在 `mcp.json` 或 `.mcp.json` 里声明了 MCP，可能被标成**仅限桌面端**（Desktop only），远程 HTTPS 也一样。标了仅限桌面端的插件不能在网页版 ChatGPT 里运行。ziwei 的插件带 `.mcp.json`。网页能不能用，真机要验。
</Callout>

<Accordions>
  <Accordion title="备用：自定义 MCP">
    这是另一条路。URL 填 `https://ziwei.x-haose.com/mcp`，无鉴权，然后 Create、安装，对话里用 `@` 选用。上面的添加插件市场不走这个地址。

    这条路没有插件里的 Skill，把 [C 的说明](#c-没有-skill-时)贴进自定义说明。官方英文文档称该入口为 Add custom MCP server，认证项是 No authentication，确认后是 Create as a plugin。协议支持 SSE 与 streaming HTTP。见 [Add custom MCP server](https://developers.openai.com/api/docs/guides/custom-mcp-server)。
  </Accordion>
</Accordions>

### Grok [#grok]

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

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

```bash title="Grok"
grok mcp add --transport http ziwei https://ziwei.x-haose.com/mcp
```

或手写：

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

见 [MCP Servers](https://docs.x.ai/build/features/mcp-servers)。装上之后同样贴 [C 的说明](#c-没有-skill-时)。

### Codex [#codex]

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

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

等价命令：

```bash title="Codex"
codex mcp add ziwei --url https://ziwei.x-haose.com/mcp
```

不要加 bearer token，也不要跑 `codex mcp login`。没有任何凭证来源时，Codex 可以无认证连接。桌面端或 IDE 里选 Streamable HTTP，URL 填同一地址。见 [Model Context Protocol](https://developers.openai.com/codex/mcp)。

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

## C. 没有 Skill 时 [#c-没有-skill-时]

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

### 中文 [#中文]

```text title="说明"
你是紫微斗数解读助手。公网 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 [#english]

```text title="Instructions"
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](#a-装插件)。这里是插件没装上、或客户端只有一份配置文件时的形状。

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

```json title="Cursor"
{
  "mcpServers": {
    "ziwei": {
      "url": "https://ziwei.x-haose.com/mcp"
    }
  }
}
```

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

```json title="Claude"
{
  "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` 时走该目录）：

```json title="Cascade"
{
  "mcpServers": {
    "ziwei": {
      "serverUrl": "https://ziwei.x-haose.com/mcp"
    }
  }
}
```

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

## 装上之后怎么说 [#装上之后怎么说]

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

| 你说                        | 模型调用      |
| ------------------------- | --------- |
| 「帮我排个盘：公历 2000-8-16，寅时，女」 | `chart`   |
| 「用白话讲讲这张盘」                | `to_text` |

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

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

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

<Callout type="warn" title="别让模型自己安星">
  它算不准干支与安星，而且错得看不出来。盘只从 `chart` / `to_text` 来。
  模型若开始凭记忆报星，让它重新调用工具。这条分工的展开说明见[让 AI 解读命盘](/zh/docs/guide/guides/llm)。
</Callout>

## 已冻的契约 [#已冻的契约]

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

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

```json title="chart / to_text 最短入参"
{
  "calendar": "solar",
  "date": "2000-8-16",
  "timeIndex": 2,
  "gender": "female"
}
```

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

| 字段          | 必填   | 取值                                                           |
| ----------- | ---- | ------------------------------------------------------------ |
| `calendar`  | 是    | `solar` 公历，`lunar` 农历                                        |
| `date`      | 是    | `YYYY-M-D`，如 `2000-8-16`。公历年份 1583–9999                      |
| `timeIndex` | 是    | 整数 0–12。0 早子时，12 晚子时，见[下表](#时辰)                              |
| `gender`    | 是    | `male` 或 `female`                                            |
| `language`  | 否    | 默认 `zh-CN`。另有 `zh-TW` `en-US` `ja-JP` `ko-KR` `vi-VN`        |
| `fixLeap`   | 否    | 默认 `true`，只对公历有意义                                            |
| `leap`      | 农历必填 | `notLeap`、`leap`、`leapFixed`                                 |
| `config`    | 否    | 六个分界开关。省略即 iztro 默认，见 [Config](/zh/docs/guide/guides/config) |

默认盘面语言是简体中文。给模型喂中文盘，比喂英文意译星名更稳，见[让 AI 解读命盘](/zh/docs/guide/guides/llm#用中文盘喂模型)。

### `chart` [#chart]

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

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

| 字段                | 取值                       |
| ----------------- | ------------------------ |
| `targetDate`      | 公历 `YYYY-M-D`            |
| `targetTimeIndex` | 0–12，与 `targetDate` 成对出现 |

### `to_text` [#to_text]

同一组出生参数，返回 `{ "text": "..." }`。`text` 是 Markdown，不是 `astrolabe_to_prompt` 那种带指令的提示词。格式见[语义化文本](/zh/docs/guide/guides/to-text)。

| 字段                 | 默认      | 含义                                                     |
| ------------------ | ------- | ------------------------------------------------------ |
| `knowledge`        | `true`  | `true` 用内嵌知识包，释义跟在事实旁；`false` 只有盘面事实                   |
| `includeHoroscope` | `false` | `true` 时必须带 `targetDate` 与 `targetTimeIndex`，正文是本命盘接运限 |

## 时辰 [#时辰]

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

| 索引 | 时辰  | 时间          | 索引 | 时辰  | 时间          |
| -- | --- | ----------- | -- | --- | ----------- |
| 0  | 早子时 | 00:00–01:00 | 7  | 未时  | 13:00–15:00 |
| 1  | 丑时  | 01:00–03:00 | 8  | 申时  | 15:00–17:00 |
| 2  | 寅时  | 03:00–05:00 | 9  | 酉时  | 17:00–19:00 |
| 3  | 卯时  | 05:00–07:00 | 10 | 戌时  | 19:00–21:00 |
| 4  | 辰时  | 07:00–09:00 | 11 | 亥时  | 21:00–23:00 |
| 5  | 巳时  | 09:00–11:00 | 12 | 晚子时 | 23:00–24:00 |
| 6  | 午时  | 11:00–13:00 |    |     |             |

<Callout type="warn" title="晚上 11 点以后是 12，不是 0">
  23:00–24:00 出生要说「晚子时」或「23 点」，不要笼统说「子时」。
  这两个索引排出的盘不同：默认配置下晚子时按次日推算日柱。
  见 [Config · 晚子时归属](/zh/docs/guide/guides/config#晚子时归属-day_divide)。
</Callout>

## 它不做什么 [#它不做什么]

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