io.github.shaozhengkun123/yarrow
I-Ching (周易) oracle: cast a hexagram, read classical commentary, get a reflection. Bilingual.
Open source Repository Open in the app JSON README (API)
About
I-Ching (周易) oracle: cast a hexagram, read classical commentary, get a reflection. Bilingual.
Details
- Kind
- MCP servers
- Topic
- No topic detected
- Publisher
- shaozhengkun123
- Origin
- official
- Category
- ferramentas
- Transport
- http
- Version
- 0.1.0
- Stars
- 1
- Last push
- 2026-05-27T11:35:45Z
- Repository state
- ativo
- Language
- TypeScript
- License
- NOASSERTION
- Added
- 2026-08-29 04:01:23
- Updated
- 2026-08-29 04:01:23
- Origin id
io.github.shaozhengkun123/yarrow
README
# Yarrow — An I-Ching oracle for the agent era
[](https://apps.apple.com/app/id6773156209)
[](https://yarrow-oracle.shaozhengkun.workers.dev/mcp)
[](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](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](LICENSE).