douglasgan/asktian

> **Chinese metaphysics inside your AI assistant.**
> 不知道就问天 · Ask tian when you don't know.
Adds 4000 years of Chinese metaphysical traditions (bazi / 八字, qimen / 奇门, five elements, daily 干支 energy) as callable tools for any AI agent that speaks the **Model Context Protocol** — Claude Desktop, Claude Code, Cursor, Windsurf, Zed, and any MCP-compatible client.
When you ask your AI assistant a timing, person, or decision question, it can quietly consult asktian before answering.
**The decision layer for AI agents.** Agents already plug in search, memory, and payments — askTIAN is the layer that gives them a *stance*: a specific, falsifiable call instead of *"it depends."* → Why it sells · 2-min quickstart
> ### ✨ Real readings, **no key needed.**
>
> The tools call the live askTIAN backend and return **real** results — daily almanac, fate
> compatibility, name analysis, day energy — straight out of the box. The read endpoints are
> **public and rate-limited** (~300 requests / 15 min). An **optional** ASKTIAN_API_KEY
> (api.asktian.com) raises the limit and unlocks the **premium
> tian.* reading tier**. market_read is a deterministic local novelty signal; best_time
> returns a guided preview (no backend endpoint yet).
---
Install
Then add to your client's MCP config:
Claude Desktop
Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):
Restart Claude Desktop. Look for the 🔌 icon — asktian should appear with 6 tools.
Cursor
Add to ~/.cursor/mcp.json:
Windsurf
Add to ~/.codeium/windsurf/mcp_config.json — same shape as above.
Zed
Add to your Zed settings under assistant.mcp_servers — same command + env.
Any other MCP client
Run asktian-mcp as a subprocess; it speaks JSON-RPC over stdio per the MCP spec.
Remote / hosted (streamable-HTTP)
For LangChain, LlamaIndex, Fetch.ai, or any agent that connects to a hosted MCP endpoint,
run the server in HTTP mode instead of stdio:
Hosted at **https://mcp.asktian.com/mcp**. Pass your key as a Bearer header:
Authorization: Bearer YOUR_ASKTIAN_API_KEY.
LangChain & LlamaIndex
Both have native MCP adapters — askTIAN works with **zero integration code**. Copy-paste
snippets in **docs/langchain-llamaindex.md**.
---
API key
**The key is optional — readings are real either way.**
| | 🆓 **No key** (default) | 🔑 **With key** |
|---|---|---|
| Setup | nothing — works instantly | get a key at api.asktian.com |
| Readings | **real** — live api.asktian.com backend (daily almanac, compatibility, name analysis, day energy) | same real readings |
| Rate limit | ~**300 requests / 15 min** (per IP) | **higher limits** |
| Premium tian.* tier | — | **unlocked** |
| Cost | **free** | per the key's plan |
**To use a key** (higher limits + premium tier), set ASKTIAN_API_KEY in your client config:
Hosted (streamable-HTTP)? Pass it as a header instead: Authorization: Bearer at_live_....
---
The 6 tools
1. asktian_daily_reading
Personalized daily energy reading for a person.
**Use when:** user asks how today will be, what colors to wear, what direction to face their desk, daily guidance.
2. asktian_compatibility
Fate compatibility between two people. Returns qualitative label first (e.g. *"互补型 Complementary"*), then numeric score (hidden if <60 per asktian design principles — low compat should never feel like rejection).
**Use when:** "will this person and I work", "compatibility check", "is this a good match".