bible-mcp

A read-only MCP server over the Bible Ontology graph, rebuilt as Next.js + xmcp (TypeScript) from app2/mcp.py and app2/mcp_backend.py.

The graph holds the people, events, places, ideas and words of the Bible, and every relation cites the verse it rests on. The server takes no doctrinal position: where a link is a reading rather than a statement of the text, it says so.

• MCP endpoint: POST /mcp (Streamable HTTP), served by the Next.js route in src/app/mcp/route.ts.

• Home page: /.

• Tools: start, search, fetch, get_relations, get_verse, get_word.

• Resources: bibleontology://about, method, licensing, version.

• Data: a snapshot in ontology-data/ (plain JSON), also seedable into MongoDB.

• Production: https://bible-mcp-alpha.vercel.app/mcp — Vercel project wonglok/bible-mcp. Vercel serves the JSON snapshot shipped with the /mcp function (outputFileTracingIncludes in next.config.ts); a local MongoDB is not reachable from there.

Quick start

npm install
npm run build       # xmcp build, then next build
npm start           # http://localhost:3000/mcp

For development:

npm run dev         # xmcp dev + next dev

A local client is already registered in .mcp.json as bible-mcp-local (http://localhost:3000/mcp); approve it once in your MCP client.

Try it:

curl -s http://127.0.0.1:3000/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'MCP-Protocol-Version: 2025-06-18' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
       "params":{"name":"fetch","arguments":{"id":"card:david"}}}'

Related MCP server: Feason Context MCP Server

Data snapshot

ontology-data/ is produced once from the bibleontology-main checkout by the site's own functions, then served read-only by TypeScript. Nothing at run time writes or fetches the graph.

# from loklok/bible-mcp, with app2/ and src/ one level up:
python3 scripts/export-ontology-data.py --out ontology-data

The export uses the reference implementation as the oracle (it imports app2/server.py), so the site's grouping, hop inputs and word fields are exactly its own. Files are plain JSON; no .gz files are read or written.

export-ontology-data.py and reference-diff.py read the site from the parent bibleontology-main checkout (app2/, src/, ontology/, out/). The committed ontology-data/ snapshot is enough to run and verify the server; regenerating it needs that checkout.

MongoDB (optional)

MongoDB Community is installed on this machine (/opt/homebrew/bin/mongod) and Mongoose is a project dependency. The JSON files stay the default; to store and read the snapshot from MongoDB instead:

# seed from ontology-data/*.json into bible_mcp
npm run seed

BIBLE_MCP_STORE=mongodb \
MONGODB_URI=mongodb://127.0.0.1:27017/bible_mcp \
npm start

Collections: snapshot (meta, addresses, schema, search), entities, verses, verse_links, words, themes, questions. src/lib/mongo.ts loads them once into memory, so every answer is still a lookup. See .env.example.

Verification

npm start            # one terminal
npm run verify       # smoke-test every tool, cursor, error path and resource
npm run diff         # compare 22 answers with app2/mcp.py, field by field

# the same checks against the deployment
MCP_URL=https://bible-mcp-alpha.vercel.app/mcp npm run verify
MCP_URL=https://bible-mcp-alpha.vercel.app/mcp npm run diff

scripts/reference-diff.py loads the site's own data and MCP core and diffs the structuredContent of both servers. 21 of 22 answers are identical. The remaining one (card:event_creation_of_heavens_and_earth) differs only in the order of two cast rows in a tie; the Python reference itself returns a different order across its own processes (string hash randomisation), so no snapshot can match all runs.

How faithful it is

• Hop rules (mcp_backend.py) are ported: a hop is a relation that hands over its verse; strength ordering with _diversify; the card's category order; readings marked reading; word matches marked match; two original-language words at most; themes in the body and never as hops.

• Protocol shaping (mcp.py) is ported: links carry iri, certainty, voice and definition; moves, map, next_cursor, the 60,000-byte budget; content[0] is the structured JSON and every link is also a resource_link.

• xmcp owns the transport, initialize, tools/list and resources/*; server identity and instructions live in xmcp.config.ts.

• Search ranks names, akas, major themes, passages and phrases like the site's own ranking, including "a part after its whole". The extra small doors the site adds (Strong's rows, word-behind-English rows, loose word matches) are not ported.

Layout

src/app/mcp/route.ts     the xmcp handler (GET + POST)
src/app/page.tsx         the home page
src/tools/*.ts           one file per tool
src/resources/…          the four bibleontology:// resources
src/lib/data.ts          loads the snapshot (JSON, or MongoDB)
src/lib/backend.ts       the hop rules and search (port of mcp_backend.py)
src/lib/mcp.ts           links, moves, map, cursors, budget, tool payloads (port of mcp.py)
src/lib/mongo.ts         optional MongoDB store
scripts/export-ontology-data.py   builds ontology-data from the site
scripts/seed-mongo.mjs            loads the JSON snapshot into MongoDB
scripts/verify.mjs                end-to-end smoke test
scripts/reference-diff.py         parity diff against app2/mcp.py
GANTT.md                          plan and critical path

Licensing

Two licences, by kind of work — see LICENSING.md:

• The code is Apache License 2.0 (LICENSE).

• The ontology-data/ snapshot is CC BY 4.0 (LICENSE-DATA).

The graph: Bible Ontology (bibleontology.org), CC BY 4.0. Its sources keep their own terms and are credited in every answer's sources:

• MACULA Hebrew and Greek Linguistic Datasets — © 2022–2024 Biblica, Inc., CC BY 4.0.

• The Holy Bible, Berean Standard Bible — public domain.

• STEP Bible's Translators Brief lexicons (Tyndale House, Cambridge) — CC BY 4.0.

• A word's senses from the UBS dictionaries (where present) are CC BY-SA 4.0, not the graph's licence; an answer carrying them says so and credits them in sources.

This server is read-only and states no doctrinal position.