mcp.wheelofheaven.world

# mcp.wheelofheaven.world

Read-only [MCP](https://modelcontextprotocol.io/) server for the Wheel of Heaven corpus.
It wraps the static JSON API at [api.wheelofheaven.world](https://api.wheelofheaven.world/v1/) so AI agents can search and retrieve the corpus with full epistemic metadata (claim types, editorial passes, citations).

Design rationale and tool-surface spec: `.claude/plans/strategy-mcp-server.md` in the [org `.claude` repo](https://github.com/wheelofheaven/.claude).

## Endpoints

- `/mcp` — Streamable HTTP (canonical)
- `/sse` — legacy SSE transport
- `/` — server info (JSON)

## Tools

Fact layer — source-grounded data, no interpretation applied:

| Tool | Purpose |
|---|---|
| `search_corpus` | Fuzzy full-text search over wiki, timeline, library books, articles, and news (~290 documents; token-AND with OR fallback) |
| `get_entry` | One wiki/timeline/articles/news entry as markdown with `claim_type`, `editorial_pass`, typed related-content edges, and canonical citation URLs; 9-language support via `lang` |
| `get_passage` | A chapter of a digitized primary source text as numbered paragraphs with stable reference IDs (e.g. `GEN-1:26`); `ref` filters to one verse |
| `get_source` | Bibliography lookup by stable ID or search — every record carries the source-program classification (family, stance, relation), critical sources included |
| `compare_traditions` | Rows from the comparative datasets: flood-myths, divine-council-index, theomachy-crossrefs, world-ages, prophets-and-religions |
| `query_graph` | Typed 1-hop ego network of any corpus node (`see_also`, `in_body`, `cites_source`, `same_tradition`, `same_age`, `comparison_of`) |

Interpretation layer — explicitly the project's own reading, labeled as such:

| Tool | Purpose |
|---|---|
| `get_interpretation` | The Wheel of Heaven framework's reading of a topic (curated context documents, or the closest wiki entry), always carrying an interpretation-layer notice |
| `get_method` | The editorial methodology: claim-type taxonomy, six-source rule, editorial passes — how to weigh everything else |

Meta:

| Tool | Purpose |
|---|---|
| `get_glossary_term` | Core terminology with renderings in all 9 site languages (exact-id match first) |

Resources: the six `/v1/context/*` narrative documents (`woh://context/{overview,hypothesis,terminology,timeline,sources,method}`) plus `woh://llms.txt`.

## Development

```bash
npm install
npm run dev        # wrangler dev on :8787
npm run typecheck
npm run deploy     # wrangler deploy (needs Cloudflare auth)
```

The server is stateless over the upstream API: every tool call fetches
`api.wheelofheaven.world/v1/…`, with the ~600 KB search corpus cached
in-memory per isolate for one hour (matching the API's edge-cache TTL).

## Architecture

- Cloudflare Workers + [`agents`](https://www.npmjs.com/package/agents) SDK (`McpAgent` Durable Object)
- `src/server.ts` — transport-agnostic tool registration (reused by the future npm stdio build)
- `src/api.ts` — `/v1/` client + search-corpus cache
- `src/html.ts` — deterministic `body_html` → markdown conversion

## Related repositories

- [api.wheelofheaven.world](https://github.com/wheelofheaven/api.wheelofheaven.world) — the static JSON API this server wraps
- [www.wheelofheaven.world](https://github.com/wheelofheaven/www.wheelofheaven.world) — the human-facing site
- [core](https://github.com/wheelofheaven/core) — the research corpus (claim model; `get_claim` lands here in v2)

## License

CC0-1.0 — like the corpus itself.