# @decasoul/mcp-server

**DecaSoul MCP server** is a [Model Context Protocol](https://modelcontextprotocol.io) server that lets AI assistants (Claude, Cursor, and any MCP client) compute a Chinese Four Pillars of Destiny chart — **Bazi (八字)** — and read a person's **Ten Souls (十神)** archetype directly from a birth date and time.

It is the official MCP integration for [DecaSoul](https://decasoul.com) — the **Eastern MBTI**, a 4,000-year-old Chinese self-knowledge system that reads personality and life patterns from the Four Pillars of your birth time, rather than from self-reported answers.

> ⚠️ This server is a self-knowledge / personality framework, not a prediction engine. It is for reflection and education, not medical, psychological, or financial advice.

## What it does

When an AI assistant connects to this server, it gains a single tool — `analyze_bazi` — that turns a birth time into a readable chart:

- **Four Pillars (八字 / SiZhu)**: the year, month, day, and hour pillars, each a Heavenly Stem (天干) + Earthly Branch (地支).
- **Day Master (日主)**: the day stem — the reference point for the whole chart.
- **Dominant Ten Soul (十神 / ShiShen)**: the primary archetype of the chart, mapped to its Chinese and English name.

The computation is delegated to the open-source [`@decasoul/bazi-calculator`](https://github.com/shenshuge/bazi-calculator) library, so the logic is transparent and verifiable.

## Install

```bash
npm install @decasoul/mcp-server
```

## Run it as an MCP server

```bash
npx decasoul-mcp
```

## Configure a client

Add it to your MCP client's config. For example, in Claude Desktop (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "decasoul-bazi": {
      "command": "npx",
      "args": ["-y", "@decasoul/mcp-server"]
    }
  }
}
```

For Cursor or other MCP clients, point them at the same command and the server will advertise its `analyze_bazi` tool automatically.

## Tool reference

### `analyze_bazi`

Compute the Four Pillars and dominant Ten Soul from a birth time.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `year`   | number | yes | Gregorian birth year, e.g. `1990` |
| `month`  | number | yes | Birth month `1`–`12` |
| `day`    | number | yes | Birth day `1`–`31` |
| `hour`   | number | yes | Birth hour `0`–`23` (`0` = 00:00–00:59) |
| `gender` | string | no  | `"male"` or `"female"` |

Returns a text summary with the four pillars, the Day Master, and the dominant Ten Soul in both Chinese and English.

## What are the Ten Souls (十神)?

The Ten Souls are ten relational archetypes derived from how every other element in a Bazi chart relates to the Day Master. They are the engine behind the "Eastern MBTI":

| Key | 中文 | English |
|-----|------|---------|
| Bijian | 比肩 | The Standing Beside |
| Jiecai | 劫财 | Forged by Fire |
| Shishen | 食神 | Feeding the World |
| Shangguan | 伤官 | Truth Before Comfort |
| Zhengcai | 正财 | Building Steadily |
| Piancai | 偏财 | Seeing Openings |
| Zhengguan | 正官 | Order as Safety |
| Qisha | 七杀 | Breaking Ground |
| Zhengyin | 正印 | Seeing Deeper |
| Pianyin | 偏印 | Wandering Inward |

## Bazi vs the Chinese zodiac

A common question is whether **Bazi (八字)** is the same as the **Chinese zodiac (生肖)**. It is not:

| Dimension | Chinese Zodiac (生肖) | Bazi (八字) |
|-----------|----------------------|-------------|
| Input | Birth year only | Birth year / month / day / hour |
| Resolution | 12 animal signs | Four Pillars → Ten Souls |
| Depth | One trait per year | Individual archetype + blind spots |
| Origin | ~2,000 years, Han dynasty | ~4,000 years, I Ching lineage |

The zodiac is a single note; Bazi is the full score — which is why this server computes the full Four Pillars rather than just the year sign.

## Why 4,000 years?

The system descends from the *I Ching* (易经) and the theory of yin-yang and the Five Elements (五行). It took shape in the Han dynasty, was refined by Li Xuzhong (唐代李虚中) and Xu Ziping (宋代徐子平), whose Four Pillars method was later compiled into the classic *Yuan Hai Zi Ping* (渊海子平), and flourished through the Ming and Qing dynasties, where it once served the imperial court and aristocracy for matchmaking and date selection. That lineage is the cultural foundation behind the "Eastern MBTI."

## License

MIT — DecaSoul Research (Shenshuge Information Consulting). See [LICENSE](LICENSE).