# yarrow [Health: Active]

**Category:** 🔮 Spirituality & Esoterica  
**Repository:** https://github.com/shaozhengkun123/yarrow  
**GitHub Stars:** 1  
**npm Downloads (last month):** 14  
**Views:** 3  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/yarrow

## Description
I-Ching (周易) oracle: cast a hexagram, read classical commentary, get a reflection. Bilingual.

## Tools
Capabilities this server exposes over MCP:

- **cast_hexagram** — Cast a hexagram for an I-Ching consultation. Returns the primary hexagram, the six lines (6=old yin, 7=young yang, 8=young yin, 9=old yang from bottom to top), any moving lines, and the changing hexagram if there are moving lines. Pass `seed` to make the cast deterministic (useful for testing or for reproducing a reading).
- **lookup_hexagram** — Return the full classical sources for a hexagram by its number (1–64): judgment (卦辞), image (大象), Tuan commentary, Zhu Xi 周易本义, Yang Tian Cai modern explanation, Yarrow's separately labelled Chinese reading aid, and historical anecdote — with available Chinese and English source material.
- **lookup_yilin** — Look up the 焦氏易林 verse for a primary hexagram changing into another hexagram. This is a local classical-source lookup, not an AI reading.
- **cast_tarot** — Draw one upright Major Arcana card for reflection. Uses a deterministic one-card Waite-Smith Major Arcana method and returns a selected source excerpt from Arthur Edward Waite's public-domain 1910/1922 text. Pass `seed` to reproduce the same draw.
- **divine** — Ask the I Ching. See your next step. Cast a hexagram, show the classical sources first, then offer a thoughtful reflection grounded in those sources. Sources first. Reflection, not prediction. The divine name remains stable for oracle/divination client compatibility. Supports English, Chinese, Japanese, Korean, Spanish, French, German, Portuguese, Italian, Russian, Arabic, Hindi, Indonesian, and English+Chinese bilingual output. Daily quota: 30 completed readings per device_id (or per anonymous IP if no device_id is supplied); timeout, provider failure, incomplete response, and cancellation do not consume it.
- **tarot_reading** — Ask one real question through a single upright Waite-Smith Major Arcana card. Returns a direct calibrated answer first, the named card and bound Arthur Edward Waite 1910 source excerpt, a practical reality check, and one observable next step. No reversals, astrology, redraw loop, or guaranteed prediction. Daily quota is shared with completed divine and Two Lenses readings.
- **two_lenses** — Bring one real question to two independent symbolic traditions: a source-first I-Ching cast and one upright Waite-Smith Major Arcana card. Returns a clear calibrated answer first, then five grounded sections covering the I Ching lens, Tarot lens, shared themes, different emphasis, and next step. Direction without guaranteed prediction or mutual-confirmation claims. Daily quota is shared with completed divine readings.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "yarrow": {
    "command": "npx",
    "args": ["-y","@shaozhengkun/yarrow-mcp"]
  }
}
```

## Documentation & README

# Yarrow — An I-Ching oracle for the agent era

[![App Store](https://img.shields.io/badge/App%20Store-iOS-black?logo=apple)](https://apps.apple.com/app/id6773156209)
[![MCP](https://img.shields.io/badge/MCP-2025--03--26-blueviolet)](https://yarrow-oracle.shaozhengkun.workers.dev/mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

Yarrow lets you (and your agents) consult the *Book of Changes* — cast a hexagram, read the classical sources, and get a Wilhelm/Baynes-style reflection. Offline-first iOS app, plus a public MCP server so any LLM agent can reach the same oracle.

> *"The I-Ching does not predict; it mirrors. The question you bring decides the reading."*

## What's in this repo

| Path | What |
| --- | --- |
| `src/` | Cloudflare Workers source — public MCP endpoint + iOS app proxy |
| `src/data_hexagrams.json` | 64 hexagrams with bilingual classical sources (杨天才 / 朱熹 / 断易天机 / 白话题解) |
| `src/hexagram.ts` | Deterministic casting (coins / yarrow stalks / random), seeded by FNV-1a + mulberry32 |
| `src/mcp.ts` | MCP JSON-RPC 2.0 handler (3 tools, 30 readings/day per anonymous caller) |
| `.claude-plugin/marketplace.json` | Claude Code / Codex plugin marketplace manifest |
| `skills/yarrow/SKILL.md` | The Yarrow skill — pluggable into any Claude Code or Codex install |
| `npm/yarrow-mcp/` | `@shaozhengkun/yarrow-mcp` — stdio bridge for clients that don't speak HTTP MCP |
| `submissions/` | Drafts for modelcontextprotocol/servers, Smithery, mcp.run |
| `INTEGRATIONS.md` | Copy-paste configs for Claude Code / Claude Desktop / Codex / Hermes |

The iOS source lives separately at [`yarrow-ios`](https://github.com/shaozhengkun123/yarrow-ios) (TODO).

## For users

### 📱 iOS app

[**Download on the App Store →**](https://apps.apple.com/app/id6773156209) · $4.99 · iOS 17+ · no tracking, no account.

All 64 hexagrams and their classical commentary ship in the app; AI reading is optional and runs through this Worker.

### 🤖 Agents

**Claude Code** — install the plugin:

```bash
claude plugin marketplace add https://github.com/shaozhengkun123/yarrow
claude plugin install yarrow
```

**Claude Desktop** — add to `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "yarrow": { "url": "https://yarrow-oracle.shaozhengkun.workers.dev/mcp" }
  }
}
```

**Codex CLI / Hermes / older Claude Desktop** — use the stdio bridge:

```bash
npx @shaozhengkun/yarrow-mcp
```

Or pin it in your client's config — see [INTEGRATIONS.md](https://github.com/shaozhengkun123/yarrow/blob/HEAD/INTEGRATIONS.md) for every platform.

**Anyone with `curl`** —

```bash
curl -s -X POST https://yarrow-oracle.shaozhengkun.workers.dev/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{
    "name":"divine",
    "arguments":{"question":"Should I take the new job?","locale":"en"}
  }}'
```

## The MCP tools

| Tool | Purpose |
| --- | --- |
| `cast_hexagram` | Toss the coins / cast the stalks. Returns primary hexagram + moving lines + changing hexagram, all metadata. Deterministic if you pass `seed`. |
| `lookup_hexagram` | Get a hexagram's classical text — Wilhelm-style header, judgment, image, and 杨天才 / 朱熹 / 断易天机 / 白话 commentaries. |
| `divine` | One-shot reading: casts, looks up, and generates a Wilhelm/Baynes-style reflection grounded in the sources. 30/day per anonymous caller. |

## Self-hosting

This Worker is MIT — fork, deploy your own, point your agents at your URL.

```bash
git clone https://github.com/shaozhengkun123/yarrow
cd yarrow
npm install
npx wrangler login
npx wrangler kv:namespace create QUOTA          # copy id into wrangler.toml
echo -n '<your OpenAI-compatible chat URL>' | npx wrangler secret put PROXY_URL
echo -n '<your API key>'                   | npx wrangler secret put PROXY_KEY
npx wrangler deploy
```

Your endpoint will be `https://yarrow-oracle.<your-subdomain>.workers.dev`.

## Boundaries

Yarrow is **for reflection, not prediction**. The system prompt baked into the Worker refuses:

- fortune-telling / specific future predictions
- medical, legal, or financial advice
- requests to "reveal what will happen"

The classical voice is direct; the framing is Jungian. This is the line we draw, in the iOS app and the MCP both.

## License

MIT for code; classical sources are in the public domain. See [LICENSE](https://github.com/shaozhengkun123/yarrow/blob/HEAD/LICENSE).