# ming-metaphysics-mcp

Five Chinese metaphysics engines as MCP tools for Claude Desktop and any MCP-compatible client.

## vs Cantian's `bazi-mcp`

| Dimension | Cantian `bazi-mcp` | Ming `ming-metaphysics-mcp` |
|---|---|---|
| **Arts covered** | BaZi only | **All five** — BaZi + QMDJ + ZWDS + Feng Shui + I Ching |
| **Engine depth** | Good BaZi implementation | 9.0–9.5/10 expert-verified across all five engines |
| **Classical sourcing** | Not documented | 子平真詮, 淵海子平, 紫微斗數全書 + 108-title library cited |
| **Output quality** | Competent readings | Scholar-validated, bilingual (EN/ZH), report-grade depth |
| **Consultation funnel** | None | Master reading available via Ming Bot (link TBA) |
| **Kua + Eight Mansions** | ❌ | ✅ |
| **QMDJ timing** | ❌ | ✅ (sxtwl Ju computation) |
| **I Ching (Liu Yao)** | ❌ | ✅ (classical 納甲法) |

---

## Tools

| Tool | Engine | Description |
|---|---|---|
| `ming_bazi_analyze` | BaZi 八字 | Four Pillars chart — Day Master, pattern, luck pillars |
| `ming_qmdj_direction` | QMDJ 奇門 | Optimal direction + timing window for a date |
| `ming_zwds_chart` | ZWDS 紫微 | Twelve-palace natal chart with 四化 transformations |
| `ming_fengshui_flying_stars` | Feng Shui 風水 | Kua number + Eight Mansions directional analysis |
| `ming_iching_cast` | I Ching 易經 | Hexagram via classical 納甲法 (Liu Yao) |
| `ming_full_forecast` | All four birth-data engines | Integrated five-engine forecast with confidence score |

---

## Engine requirement

This package is an MCP **wrapper**. It does not contain metaphysics
calculation logic — it forwards tool calls to a Ming engine endpoint over
HTTP. To use it, point `MING_API_URL` at a running engine.

Two ways to get an engine:

1. **Hosted endpoint (preferred, when available).** A public Ming endpoint
   will be announced; once available, configure `MING_API_URL` to point at
   it and you're done.
2. **Self-host.** The Ming engine itself is currently a closed-source
   reference implementation. If you have access to the Ming codebase, run
   `uvicorn api.main:app --port 8000` and point this MCP at `localhost:8000`.

Without a reachable engine, the MCP server starts and lists tools, but tool
calls return an HTTP error.

## Install

### Step 1 — Ensure an engine is reachable

See "Engine requirement" above.

### Step 2 — Install the MCP server

```bash
npm install -g @espivc/ming-metaphysics-mcp
```

### Step 3 — Add to `claude_desktop_config.json`

- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "ming": {
      "command": "ming-metaphysics-mcp",
      "args": [],
      "env": {
        "MING_API_URL": "http://localhost:8000"
      }
    }
  }
}
```

Restart Claude Desktop. The Ming tools will appear in the tools list.

### Verification

In Claude Desktop:

```
Using the ming_bazi_analyze tool, analyze the chart for someone born 1990-03-15, male, in Singapore.
```

You should get a full BaZi reading. If the tool errors, verify the Python engine is running at port 8000.

---

## Endpoint Gaps

The following capabilities require FastAPI expansion before they fully function as specified. Each is flagged with a note in the tool response — no silent failures.

| Gap | Affected Tool | Required FastAPI Change |
|---|---|---|
| **Annual flying star map for a specific year** | `ming_fengshui_flying_stars` | `/consult` needs a `year` query parameter to compute annual stars for years other than current |
| **`forecast_year` parameter** | `ming_full_forecast` | `/consult` computes annual analysis against the current year internally; it does not accept a target year |
| **Full ISO casting_timestamp** | `ming_iching_cast` | `/iching-cast` accepts `date` (YYYY-MM-DD) and `hour_branch` separately, not an ISO 8601 timestamp; only the date portion is forwarded |
| **`goal: "bazi"/"qmdj"/"zwds"` routing** | All individual tools | The spec assumed `/consult` would accept engine-name goals, but the real endpoint uses purpose goals (`wealth/career/health/relationship/general`). Individual tools route to dedicated per-engine endpoints instead (`/analyze`, `/zwds`, `/qmdj`, `/iching-cast`) |

To implement year-specific flying stars or forecast_year support, add those parameters to `/consult` in `api/main.py` and update the corresponding tool handlers here.

---

## Development

```bash
git clone <this-repo>
cd ming-metaphysics-mcp
npm install
npm run build          # compile TypeScript → dist/
npm test               # smoke tests (no engine required)

# With engine running at localhost:8000:
npx ts-node scripts/benchmark.ts --tool all --iterations 5
```

### Environment variables

| Variable | Default | Description |
|---|---|---|
| `MING_API_URL` | `http://localhost:8000` | Base URL of the Ming FastAPI engine |

### Latency targets

| Tool | Target |
|---|---|
| `ming_bazi_analyze` | < 3s |
| `ming_qmdj_direction` | < 3s |
| `ming_fengshui_flying_stars` | < 3s |
| `ming_zwds_chart` | < 5s |
| `ming_full_forecast` | < 5s |
| `ming_iching_cast` | < 3s |

If any tool exceeds 5s consistently, check the engine bottleneck and consider adding `timeout: 10000` to the MCP config.

---

## Auth

None at the wrapper level — this server is open-source and free (MIT
license). Authentication, if any, is enforced by whatever endpoint
`MING_API_URL` points at.

---

## For a complete five-engine reading

A guided five-engine consultation (BaZi + ZWDS + QMDJ + Feng Shui + I Ching
synthesised by Master Chen) is available via Ming's Telegram bot. Link will
be published once the bot is in public beta.

---

## Privacy

This MCP wrapper itself does not collect data. It forwards your tool
arguments (birth date, hour, gender, question text) to whichever
`MING_API_URL` you configured. If you point at a hosted endpoint, that
endpoint receives the data — read its privacy policy. If you self-host,
nothing leaves your network.

Birth data is sensitive. If you're configuring this for end users, be
explicit about which endpoint receives their inputs.

---

## Project status

This package is at version `1.0.0`. The MCP protocol surface (6 tools, JSON
schemas, response shapes) is stable. The underlying Ming engine evolves
faster — minor numeric changes in tool responses are normal.

Contributions welcome — see `CONTRIBUTING.md`.

---

## License

MIT — see `LICENSE`.