◈ Reference · Using the Grimoire

Using the Grimoire

The archive is 81 catalogues and 3,062 entries, with 35,010 references between them — and every one of those references resolves. This page is how to get at it: from an assistant, from code, or as a file.

Free to use. CC BY-SA 4.0 — attribute it and share alike.

Three ways in

MCP For AI assistants

A Model Context Protocol server, so an assistant can look things up instead of guessing. Twelve tools: search, structured filtering by field, field discovery, lookup, the full record, graph traversal and pathfinding, the catalogues, timing and what is coming next, and which workings suit the conditions.

No dependencies. No build step. Reads the JSON off disk.

HTTP For code

A read-only JSON API over the same corpus and the same query core. No key, open CORS, ETags for caching, and every response tells you which version of the corpus answered.

Public and stable. Nothing to install.

JSON For everything else

One file with the whole corpus plus the table that says how it joins together, about 4 MB — and it is what the MCP server reads if you would rather not clone anything. Work offline, forever.

The attribution and licence travel inside the file.

MCP — for AI assistants

The server is a single file with no dependencies. It reads the corpus from a checkout if you have one, or from the downloaded bundle if you do not: 

git clone https://github.com/formisfate/grimoire-surface.git
cd grimoire-surface
curl -L -o grimoire-bundle.json https://ensoul.so/api/grimoire/bundle

claude mcp add grimoire -- node "$PWD/mcp/server.mjs" --bundle "$PWD/grimoire-bundle.json"

Or, for any client with a JSON config:

{
  "mcpServers": {
    "grimoire": {
      "command": "node",
      "args": ["/absolute/path/to/grimoire-surface/mcp/server.mjs"]
    }
  }
}

Ask it things like “what connects basil to Mars”, “what's the planetary hour”, or “which workings suit tonight”. Every answer carries its provenance, so an assistant can tell you who says so rather than flattening a disagreement into a fact.

HTTP — for code

Read-only JSON, same corpus, same query core as the MCP server. Open CORS, no key, no rate limit you will ever reach. 

curl https://ensoul.so/api/grimoire/overview
curl 'https://ensoul.so/api/grimoire/search?q=protection&limit=3'
curl 'https://ensoul.so/api/grimoire/fields?file=herbs'
curl -G https://ensoul.so/api/grimoire/find \
  --data-urlencode 'where={"planet":"mars","element":"fire"}'
curl https://ensoul.so/api/grimoire/entry/basil
curl 'https://ensoul.so/api/grimoire/related/mars?direction=in'
curl https://ensoul.so/api/grimoire/path/basil/protection
curl 'https://ensoul.so/api/grimoire/when?planet=venus&working=protection'
curl 'https://ensoul.so/api/grimoire/timing?lat=-33.87&lon=151.21'

Every response carries corpus.version — a content hash of the exact corpus that answered — plus an ETag, so caching is cheap and staleness is detectable.

JSON — for everything else

The bundle is the corpus plus joins.json, the table that says which values are references to other entries and which are just words. Take it and go. 

curl -L -o grimoire-bundle.json https://ensoul.so/api/grimoire/bundle
# ~4 MB — every entry + the join table

# ...and run the MCP server straight from it, no corpus checkout:
node mcp/server.mjs --bundle grimoire-bundle.json

Before you write a consumer

There is one rule, and it is not the obvious one: a value is a reference only when the corpus's join table says so. Inferring it from field names has been tried three times here and failed each time.

  • sage is four different entries — an archetype, a herb, a resin and an oil. Resolve an id to a list, not a single row.
  • element means two different systems — the Western five (plus aether) in one file, Wu Xing's five phases in another. They are not the same list.
  • exaltation points both ways — a planet's is a sign, a sign's is a planet. Same field name, opposite direction.
  • all_ is not a broken id — any value beginning all_ means “every member”. There are 30 such values and they are legal everywhere.
  • Disagreement is the design — where traditions differ, the entry records it in note rather than picking a winner. Do not “fix” that.

The full account — the join table's precedence, the meta values, and the five ways people get this wrong — is in the surface repository's docs/DATA.md.

Licence

The data is CC BY-SA 4.0. Use it, adapt it, ship it, sell it — attribute it and share adaptations under the same licence. The code is MIT.

Most of the underlying material is centuries out of copyright — Agrippa, the Golden Dawn's Book T, the Arbatel, the Key of Solomon, Liber 777. What the licence covers is the selection, the structure, the 35,010 cross-references, and the editorial work of recording where every claim comes from.