{
  "markdown": "# Yarrow — An I-Ching oracle for the agent era\n\n[![App Store](https://img.shields.io/badge/App%20Store-iOS-black?logo=apple)](https://apps.apple.com/app/id6773156209)\n[![MCP](https://img.shields.io/badge/MCP-2025--03--26-blueviolet)](https://yarrow-oracle.shaozhengkun.workers.dev/mcp)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n\nYarrow 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.\n\n> *\"The I-Ching does not predict; it mirrors. The question you bring decides the reading.\"*\n\n## What's in this repo\n\n| Path | What |\n| --- | --- |\n| `src/` | Cloudflare Workers source — public MCP endpoint + iOS app proxy |\n| `src/data_hexagrams.json` | 64 hexagrams with bilingual classical sources (杨天才 / 朱熹 / 断易天机 / 白话题解) |\n| `src/hexagram.ts` | Deterministic casting (coins / yarrow stalks / random), seeded by FNV-1a + mulberry32 |\n| `src/mcp.ts` | MCP JSON-RPC 2.0 handler (3 tools, 30 readings/day per anonymous caller) |\n| `.claude-plugin/marketplace.json` | Claude Code / Codex plugin marketplace manifest |\n| `skills/yarrow/SKILL.md` | The Yarrow skill — pluggable into any Claude Code or Codex install |\n| `npm/yarrow-mcp/` | `@shaozhengkun/yarrow-mcp` — stdio bridge for clients that don't speak HTTP MCP |\n| `submissions/` | Drafts for modelcontextprotocol/servers, Smithery, mcp.run |\n| `INTEGRATIONS.md` | Copy-paste configs for Claude Code / Claude Desktop / Codex / Hermes |\n\nThe iOS source lives separately at [`yarrow-ios`](https://github.com/shaozhengkun123/yarrow-ios) (TODO).\n\n## For users\n\n### 📱 iOS app\n\n[**Download on the App Store →**](https://apps.apple.com/app/id6773156209) · $4.99 · iOS 17+ · no tracking, no account.\n\nAll 64 hexagrams and their classical commentary ship in the app; AI reading is optional and runs through this Worker.\n\n### 🤖 Agents\n\n**Claude Code** — install the plugin:\n\n```bash\nclaude plugin marketplace add https://github.com/shaozhengkun123/yarrow\nclaude plugin install yarrow\n```\n\n**Claude Desktop** — add to `~/Library/Application Support/Claude/claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"yarrow\": { \"url\": \"https://yarrow-oracle.shaozhengkun.workers.dev/mcp\" }\n  }\n}\n```\n\n**Codex CLI / Hermes / older Claude Desktop** — use the stdio bridge:\n\n```bash\nnpx @shaozhengkun/yarrow-mcp\n```\n\nOr pin it in your client's config — see [INTEGRATIONS.md](INTEGRATIONS.md) for every platform.\n\n**Anyone with `curl`** —\n\n```bash\ncurl -s -X POST https://yarrow-oracle.shaozhengkun.workers.dev/mcp \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/call\",\"params\":{\n    \"name\":\"divine\",\n    \"arguments\":{\"question\":\"Should I take the new job?\",\"locale\":\"en\"}\n  }}'\n```\n\n## The MCP tools\n\n| Tool | Purpose |\n| --- | --- |\n| `cast_hexagram` | Toss the coins / cast the stalks. Returns primary hexagram + moving lines + changing hexagram, all metadata. Deterministic if you pass `seed`. |\n| `lookup_hexagram` | Get a hexagram's classical text — Wilhelm-style header, judgment, image, and 杨天才 / 朱熹 / 断易天机 / 白话 commentaries. |\n| `divine` | One-shot reading: casts, looks up, and generates a Wilhelm/Baynes-style reflection grounded in the sources. 30/day per anonymous caller. |\n\n## Self-hosting\n\nThis Worker is MIT — fork, deploy your own, point your agents at your URL.\n\n```bash\ngit clone https://github.com/shaozhengkun123/yarrow\ncd yarrow\nnpm install\nnpx wrangler login\nnpx wrangler kv:namespace create QUOTA          # copy id into wrangler.toml\necho -n '<your OpenAI-compatible chat URL>' | npx wrangler secret put PROXY_URL\necho -n '<your API key>'                   | npx wrangler secret put PROXY_KEY\nnpx wrangler deploy\n```\n\nYour endpoint will be `https://yarrow-oracle.<your-subdomain>.workers.dev`.\n\n## Boundaries\n\nYarrow is **for reflection, not prediction**. The system prompt baked into the Worker refuses:\n\n- fortune-telling / specific future predictions\n- medical, legal, or financial advice\n- requests to \"reveal what will happen\"\n\nThe classical voice is direct; the framing is Jungian. This is the line we draw, in the iOS app and the MCP both.\n\n## License\n\nMIT for code; classical sources are in the public domain. See [LICENSE](LICENSE).\n",
  "bytes": 4367,
  "sha": "680cb7e948686e1f06fd2468f1dcd62774b6d84c0729ebbc77f58ed148512020",
  "repo_slug": "shaozhengkun123/yarrow",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_shaozhengkun123_yarrow_faa4be2c/readme"
}