<div align="center">

# 易数洞察 · Yishu Insight MCP Server

**Deterministic I Ching and Zi Wei Dou Shu for AI agents.**

[![MCP](https://img.shields.io/badge/MCP-2025--03--26-blue)](https://modelcontextprotocol.io)
[![Node](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org)
[![Zero Dependencies](https://img.shields.io/badge/dependencies-0-success)](./package.json)
[![License: MIT](https://img.shields.io/badge/license-MIT-yellow.svg)](./LICENSE)
[![Live Website](https://img.shields.io/badge/live-insightapp.life-gold)](https://insightapp.life)

[English](#english) · [中文](#中文) · [日本語](#日本語)

</div>

---

<a id="english"></a>

## English

`yishu-insight-mcp` is the MCP server for [Yishu Insight (易数洞察)](https://insightapp.life). It gives your AI agent two classical Chinese systems, computed by code and not by the model:

- **I Ching (Book of Changes).** 64 hexagrams. Three-coin and Plum Blossom (time-based) casting. Original, mutual, opposite, reversed and changed hexagrams. Full classical texts and moving-line readings. Runs locally and works offline.
- **Zi Wei Dou Shu (Purple Star Astrology).** 12 palaces, 14 main stars, 23 classical patterns, Four Transformations (flying stars), synastry, a 100-year Life K-Line, a classical texts knowledge base and famous charts. Powered by the authoritative Rust engine at insightapp.life.

The LLM never guesses a chart. If the engine is unreachable, the tool returns `isError`. It never invents a result. Zero runtime dependencies. Node 18 or newer.

### Quick Start

**1. Remote Streamable HTTP (zero install)**

Endpoint: `https://insightapp.life/mcp`

Claude Desktop, Cursor, Windsurf and Cline:

```json
{
  "mcpServers": {
    "yishu-insight": { "url": "https://insightapp.life/mcp" }
  }
}
```

ChatGPT / OpenAI: add `https://insightapp.life/mcp` as a remote MCP server (ChatGPT connectors in developer mode, or the `mcp` tool of the OpenAI Responses API with `server_url`). No auth needed.

**2. Local stdio via NPX**

```json
{
  "mcpServers": {
    "yishu-insight": {
      "command": "npx",
      "args": ["-y", "yishu-insight-mcp"]
    }
  }
}
```

| Client | Where to put it |
|---|---|
| Claude Desktop | `claude_desktop_config.json` under `mcpServers` |
| Cursor | `~/.cursor/mcp.json` or `.cursor/mcp.json` |
| Windsurf | `~/.codeium/windsurf/mcp_config.json` |
| Cline | MCP Servers, Configure, `cline_mcp_settings.json` |
| Claude Code | `claude mcp add yishu-insight -- npx -y yishu-insight-mcp` |

Options: `--remote-url <url>` (or env `YISHU_INSIGHT_URL`) sets the engine for `ziwei_*` tools. Also `--help` and `--version`.
Note: local `ziwei_*` tools need network access to the engine. `iching_*` tools never do.

### Tools

| Tool | Runs | Parameters | Example |
|---|---|---|---|
| `iching_cast` | local | `method` (`coins` \| `time` \| `lines`, default `coins`), `lines` (e.g. `"788878"`: 6 old yin, 7 young yang, 8 young yin, 9 old yang, bottom to top), `changing` (e.g. `"3,5"`), `at` (`"YYYY-MM-DD HH:MM"`), `question` | `{"method":"lines","lines":"788878"}` |
| `iching_lookup` | local | one of `number` (1-64), `name` (`泰`, `地天泰`), or `upper` + `lower` | `{"upper":"坤","lower":"乾"}` |
| `ziwei_chart` | remote | `gender`, plus `solar_date` + `birth_time`, or `lunar_year`/`lunar_month`/`lunar_day`/`hour`; optional `is_leap_month`, `target_solar_year` | `{"solar_date":"1990-06-15","birth_time":"09:30","gender":"female"}` |
| `ziwei_heming` | remote | `person_a`, `person_b` (birth fields as above), `relation_type` (default `marriage`) | `{"person_a":{...},"person_b":{...}}` |
| `ziwei_life_kline` | remote | birth fields, `from_year`, `to_year` (default: birth year to +99) | `{"solar_date":"1990-06-15","birth_time":"09:30","gender":"female"}` |
| `ziwei_kb_query` | remote | `gong` plus `star` (one star) or `stars[]` (whole palace); optional `branch`, `max_len` | `{"gong":"命宫","star":"紫微"}` |
| `ziwei_famous` | remote | none (list), `slug` (one chart), or `category` | `{}` (list all) |

`iching_cast` returns `ben`, `hu`, `cuo`, `zong`, `bian` (null if no moving line), `rule`, `moving_line_texts`, `ti_yong` and `decision_guidance`.
`ziwei_chart` returns `{ source, request, result }`. `result` holds 12 palaces, 命/身宫, five-element bureau, main stars, `patterns`, `feixing` and decade/annual cycles.

Prompts: `iching_divination_prompt`, `ziwei_chart_reading_prompt`. Resources: `yishu://hexagrams/index`, `yishu://guide/methodology`.

### Try it in the browser

- Zi Wei chart: <https://insightapp.life/ziwei/chart>
- I Ching divination: <https://insightapp.life/zhouyi/divine>
- Synastry: <https://insightapp.life/ziwei/heming>
- Life K-Line: <https://insightapp.life/ziwei/life-kline>

### Develop

```bash
npm test            # node --test, spawns the real stdio server
npm pack --dry-run
docker build -t yishu-insight-mcp .
```

MIT licensed. Divination is for cultural and reflective use. It is not medical, legal or financial advice.

---

<a id="中文"></a>

## 中文

**易数洞察 MCP Server (`yishu-insight-mcp`)** 把周易与紫微斗数交给代码计算,而不是交给大模型"推演"。

### 核心特性

- **零依赖确定性引擎。** 起卦、排盘全部由程序算出,杜绝大模型算命幻觉。Node ≥ 18,零第三方依赖。
- **周易。** 六十四卦;三枚铜钱与梅花易数(时间)起卦;本卦、互卦、错卦、综卦、变卦;卦辞、彖传、大象、爻辞与动爻取辞;体用与决策提示。本地运行,离线可用。
- **紫微斗数。** 公历生日自动转农历,支持真太阳时与闰月;十二宫、十四主星、23 大经典格局;四化飞星;双人合盘;百岁人生 K 线;《紫微斗数全书》《骨髓赋》等古籍检索;名人命盘库。
- **诚实失败。** 排盘引擎不可达时明确返回 `isError`,绝不伪造星盘。

### 快速接入

**一、远程免安装(Streamable HTTP)**:`https://insightapp.life/mcp`

适用于 Claude Desktop、Cursor、Windsurf、Cline、Cherry Studio:

```json
{
  "mcpServers": {
    "yishu-insight": { "url": "https://insightapp.life/mcp" }
  }
}
```

Cherry Studio:设置 → MCP 服务器 → 添加,类型选 `streamableHttp`,URL 填 `https://insightapp.life/mcp`。

**二、本地 stdio(NPX)**

```json
{
  "mcpServers": {
    "yishu-insight": {
      "command": "npx",
      "args": ["-y", "yishu-insight-mcp"]
    }
  }
}
```

配置位置:Claude Desktop 为 `claude_desktop_config.json`;Cursor 为 `~/.cursor/mcp.json`;Cline 为 `cline_mcp_settings.json`;Claude Code 运行 `claude mcp add yishu-insight -- npx -y yishu-insight-mcp`。

可选参数:`--remote-url <url>` 或环境变量 `YISHU_INSIGHT_URL` 指定排盘引擎地址。本地模式下 `ziwei_*` 需要联网,`iching_*` 完全离线。

### 7 大工具

| 工具 | 运行位置 | 参数 | 说明 |
|---|---|---|---|
| `iching_cast` | 本地 | `method`(`coins` 铜钱 \| `time` 梅花 \| `lines` 指定爻,默认 `coins`);`lines` 如 `"788878"`(6 老阴、7 少阳、8 少阴、9 老阳,由初爻到上爻);`changing` 如 `"3,5"`;`at` 为 `"YYYY-MM-DD HH:MM"`;`question` | 起卦,返回本/互/错/综/变卦、动爻爻辞、体用、决策提示 |
| `iching_lookup` | 本地 | `number`(1-64)、`name`(`泰`、`地天泰`)或 `upper` + `lower` 三选一 | 查卦:卦辞、彖传、大象、六爻、互错综 |
| `ziwei_chart` | 远程 | `gender`,加 `solar_date` + `birth_time`,或 `lunar_year`/`lunar_month`/`lunar_day`/`hour`;可选 `is_leap_month`、`target_solar_year` | 紫微命盘:十二宫、命/身宫、五行局、主星、格局、飞星、大限流年 |
| `ziwei_heming` | 远程 | `person_a`、`person_b`(出生信息同上),`relation_type`(默认 `marriage`) | 双人合盘 |
| `ziwei_life_kline` | 远程 | 出生信息,`from_year`、`to_year`(默认出生年起 100 年) | 百岁人生 K 线 |
| `ziwei_kb_query` | 远程 | `gong` 加 `star`(单星)或 `stars[]`(整宫);可选 `branch`、`max_len` | 古籍与星曜知识库检索 |
| `ziwei_famous` | 远程 | 无参数(列表)、`slug`(单盘)或 `category`(分类) | 名人命盘 |

示例:

```json
{ "name": "ziwei_chart", "arguments": { "solar_date": "1990-06-15", "birth_time": "09:30", "gender": "female" } }
```

另有提示词 `iching_divination_prompt`、`ziwei_chart_reading_prompt`,资源 `yishu://hexagrams/index`、`yishu://guide/methodology`。

### 在线体验

- 紫微排盘:<https://insightapp.life/ziwei/chart>
- 周易占卜:<https://insightapp.life/zhouyi/divine>
- 双人合盘:<https://insightapp.life/ziwei/heming>
- 人生 K 线:<https://insightapp.life/ziwei/life-kline>

> 繁體中文使用者:以上設定與工具完全相同,網站可於語言選單切換「繁體中文」。
>
> 声明:本工具用于文化研究与自我反思,不构成医疗、法律或投资建议。MIT 许可。

---

<a id="日本語"></a>

## 日本語

**易数インサイト MCP サーバー (`yishu-insight-mcp`)** は、易経と紫微斗数の計算をコードに任せ、LLM に推測させません。

### 特徴

- **決定論的エンジン。** 卦も命盤もプログラムが計算するため、LLM のハルシネーションが入りません。Node 18 以上、依存パッケージなし。
- **易経。** 64 卦。六爻(三枚コイン)と梅花心易(時刻)による占筮。本卦・互卦・錯卦・綜卦・変卦。卦辞・彖伝・大象・爻辞、体用、判断のヒント。ローカルで動作し、オフラインでも使えます。
- **紫微斗数。** 新暦から旧暦への自動変換(閏月・真太陽時対応)。十二宮、14 主星、23 格局、四化飛星、相性診断(合盤)、100 年人生 K ライン、『紫微斗数全書』『骨髄賦』などの古典検索、著名人の命盤。
- **正直な失敗。** エンジンに接続できない場合は `isError` を返し、命盤を捏造しません。

### クイックスタート

**1. リモート MCP(インストール不要)**:`https://insightapp.life/mcp`

Claude Desktop / Cursor / Windsurf / Cline:

```json
{
  "mcpServers": {
    "yishu-insight": { "url": "https://insightapp.life/mcp" }
  }
}
```

**2. ローカル stdio(npx)**

```json
{
  "mcpServers": {
    "yishu-insight": {
      "command": "npx",
      "args": ["-y", "yishu-insight-mcp"]
    }
  }
}
```

設定ファイル: Claude Desktop は `claude_desktop_config.json`、Cursor は `~/.cursor/mcp.json`、Claude Code は `claude mcp add yishu-insight -- npx -y yishu-insight-mcp`。

`--remote-url <url>`(または環境変数 `YISHU_INSIGHT_URL`)でエンジンの URL を変更できます。ローカルでも `ziwei_*` はネットワークが必要で、`iching_*` は不要です。

### ツール一覧(7 種)

| ツール | 実行場所 | 主なパラメータ | 内容 |
|---|---|---|---|
| `iching_cast` | ローカル | `method`(`coins` \| `time` \| `lines`、既定 `coins`)、`lines` 例 `"788878"`(6 老陰、7 少陽、8 少陰、9 老陽、初爻から上爻)、`changing` 例 `"3,5"`、`at`、`question` | 占筮。本卦・互卦・錯卦・綜卦・変卦、動爻の爻辞 |
| `iching_lookup` | ローカル | `number`(1-64)、`name`(`泰`、`地天泰`)、または `upper` + `lower` | 卦の検索。卦辞・彖伝・大象・六爻 |
| `ziwei_chart` | リモート | `gender` と、`solar_date` + `birth_time`、または `lunar_year`/`lunar_month`/`lunar_day`/`hour`。任意で `is_leap_month`、`target_solar_year` | 紫微斗数の命盤 |
| `ziwei_heming` | リモート | `person_a`、`person_b`、`relation_type`(既定 `marriage`) | 相性診断(合盤) |
| `ziwei_life_kline` | リモート | 生年月日情報、`from_year`、`to_year`(既定は生年から 100 年) | 100 年人生 K ライン |
| `ziwei_kb_query` | リモート | `gong` と `star` または `stars[]`、任意で `branch`、`max_len` | 古典籍・星曜ナレッジ検索 |
| `ziwei_famous` | リモート | なし(一覧)、`slug`、または `category` | 著名人の命盤 |

呼び出し例:

```json
{ "name": "iching_lookup", "arguments": { "upper": "坤", "lower": "乾" } }
```

### Web 版で試す

- 命盤: <https://insightapp.life/ziwei/chart>
- 易経占い: <https://insightapp.life/zhouyi/divine>
- 合盤: <https://insightapp.life/ziwei/heming>
- 人生 K ライン: <https://insightapp.life/ziwei/life-kline>

> 本ツールは文化的な学びと内省のためのものです。医療・法律・投資の助言ではありません。MIT ライセンス。