Yishu Insight MCP Server

English | 简体中文 | 日本語

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

yishu-insight-mcp connects your AI agent to Yishu Insight. Calculations are performed by code, with zero runtime dependencies and Node.js 18 or newer.

• I Ching (Book of Changes): 64 hexagrams, three-coin casting, Meihua Yishu (Plum Blossom Numerology) time-based casting, and explicit six-line input. Includes original, mutual, opposite, reversed, and changed hexagrams, 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, Si Hua (Four Transformations), compatibility, a 100-Year Life K-Line, classical text lookup, and famous charts. Uses the authoritative Rust engine at insightapp.life.

• Explicit errors: unavailable engines or invalid responses produce isError; the server does not fabricate a substitute chart.

Official Web Platform & Live Tools (insightapp.life)

Explore the full platform in your browser, or connect an agent through the MCP endpoint.

View assessment on M8ven

Related MCP server: 知耘排盘 MCP Server

Quick Start

Remote Streamable HTTP

Connect a client that supports remote Streamable HTTP to https://insightapp.life/mcp. No local installation is needed. For clients that accept URL-based mcpServers configuration:

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

In clients with a setup form, select Streamable HTTP and enter the endpoint URL. Configuration fields vary by client.

The following request calls the remote HTTP endpoint directly. It uses calendar fields and clock_hour, rather than the local stdio wrapper's solar_date and birth_time fields:

curl -sS https://insightapp.life/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  --data '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "ziwei_chart",
      "arguments": {
        "year": 1990,
        "month": 5,
        "day": 15,
        "clock_hour": 14,
        "gender": "male"
      }
    }
  }'

Use tools/list on the endpoint you connect to for its current input schemas. The remote HTTP service and the local stdio wrapper expose different birth-input schemas.

Local stdio via NPX

Install Node.js 18 or newer, then add this configuration to your MCP client:

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

Use --remote-url <url> or the YISHU_INSIGHT_URL environment variable to change the Zi Wei engine base URL (default: https://insightapp.life). This is the website base URL, not the /mcp endpoint. Run --help for usage or --version for the installed version.

After installation, iching_* tools work offline. Local ziwei_* tools still require network access to the remote engine.

Local stdio Tool Reference

These seven tools use the schemas supplied by this npm package. Technical identifiers are unchanged; classical texts and engine responses may contain their original Chinese terminology. This English guide does not imply that the underlying dataset has been translated.

Birth Parameters

Always supply gender as male or female, plus one of these input forms:

Example tools/call parameters for the local stdio server:

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

An offline I Ching lookup:

{ "name": "iching_lookup", "arguments": { "number": 11 } }

Results, Prompts, and Resources

iching_cast returns ben (original), hu (mutual), cuo (opposite), zong (reversed), bian (changed; null when no line moves), rule, moving_line_texts, ti_yong, and decision_guidance.

ziwei_chart returns { source, request, result }. The engine result contains the 12 palaces, Ming Gong (Life Palace), Shen Gong (Body Palace), five-element bureau, main stars, patterns, feixing (flying stars), Da Xian (decade cycles), and Liu Nian (annual cycles).

Development

Run these commands from the repository root:

npm test
npm pack --dry-run
docker build -t yishu-insight-mcp .

The test suite uses Node's test runner, launches the actual stdio server, and exercises remote behavior with a mock engine. The package has no runtime dependencies.

License

MIT. Intended for cultural study and personal reflection; it is not medical, legal, or financial advice.