Wisdom MCP

An MCP server for agentic hybrid search over philosophical and spiritual texts, built on Kevin Owocki's Wisdom Context Window. The server only retrieves: your own model searches, reads, quotes and translates. See the design write-up.

Motivation

Ask a model what the Stoics or the Daodejing say about anger and it will often paraphrase, or invent a plausible line with a plausible reference. For texts like these, the exact words and where they come from matter.

Wisdom MCP gives the model tools instead of answers. It searches a curated corpus with keywords and embeddings, then returns the original text with a precise reference. The model does the reasoning and translation, and quotes what it actually read. The corpus can grow without retraining anything, and every quote can be checked against its source.

Related MCP server: sefaria-api-mcp

Setup

pnpm install
cp .env.example .env
pnpm build
pnpm start

The database is created at DATABASE_PATH on first boot, and migrations in migrations/ are applied in order.

Settings come from .env and the environment, which takes precedence, and are validated at startup by the server and the corpus scripts alike. Without MISTRAL_API_KEY, search falls back to keywords only.

Over either rate limit, /mcp answers 429 with a JSON-RPC error and a Retry-After header. Clients are told apart by IP, taken from X-Forwarded-For as set by the reverse proxy in front of the server. Counters are kept in memory, so a restart resets them.

/mcp rejects JSON-RPC batches, request bodies over 16 KB, and a Host or Origin header naming another host than PUBLIC_URL. Requests without Origin, as sent by non-browser clients, pass.

Corpus

pnpm corpus:import

This imports the 51 pilot works from the Wisdom Context Window, with their original-language texts, and its concept graph: 208 concepts, each with a summary, key passages and links to parallel, opposing, related and broader concepts. Downloads are cached in CORPUS_CACHE, so later runs work offline, and each run replaces the works and concepts it imports.

The cached Wisdom Context Window dump is never downloaded again on its own. To see what changed on the site first:

pnpm corpus:diff

This downloads the latest dump, without touching the cached copy, and lists the full texts on the site that are not in PILOT_WORKS yet, then the imported works a re-import would change: a different number of passage blocks, or passages no longer in the block their id points to (edited). Passage ids such as analects:123 are positional, so those works' ids would shift. It reads the database and changes nothing. Then re-import from the latest dump:

pnpm corpus:import --refresh

--refresh downloads the dump again and overwrites the cached copy. The original-language texts and the concept graph stay cached.

The corpus badge at the top of this README is static: after an import changes the counts, update it with select count(*) from texts and select count(*) from passages.

Every quotable passage has a reference and an original. Front matter, translators' notes, indexes and headings are kept but flagged is_apparatus.

The Great Learning, the Doctrine of the Mean and Mencius come from Zhu Xi's 《四書章句集注》, and follow his chapters as Legge does: the Great Learning counts from 0, the text of Confucius, then ten chapters of commentary, and Mencius is book, part and chapter (1A.1). The Wisdom Context Window gives these three with no numbers, each Chinese paragraph followed by Legge's translation of it. So each Chinese paragraph is matched to the chapter whose text it shares the most character pairs with, and the translation after it takes that chapter. The Chinese paragraphs are flagged is_apparatus, and a paragraph that runs over into the next chapter takes a range, such as 14-15.

The three Giles translations have no numbers either, and no Chinese, so they are aligned by hand in data/alignments/<work>.json: in order, the opening words of the block where each unit starts, or … and words within a block, which then takes a range such as 10.6-7. Chuang Tzŭ is a full translation and goes by chapter and Wikisource paragraph (17.12). The Book of Lieh Tzŭ is a selection, by book and paragraph of the Chinese (Giles's Book VII is the Chinese book 8, 說符, so it is 8.x). The Sayings of Lao Tzŭ rearranges sayings by theme, each taking the 王弼本 chapter it comes from, so it shares the Legge Tao Te Ching's original and readings. Giles's notes, page numbers and section titles are flagged is_apparatus.

The Art of War keeps Giles's section numbers (6.22), and each section takes the Wikisource paragraph of its chapter it falls in, or a range of them (6.6-7); his bracketed notes are apparatus. Mei's Motse and Dubs's Hsüntze are scans with footnotes, page heads and margin summaries run into the text, aligned by hand like the Giles translations, by chapter (or book) and Wikisource paragraph: a footnote runs from the first one on a page to the next page head. Dubs translates 19 of the 32 books and the eulogy that ends book 32. Legge's Yi King is also a scan, whose notes are told from the text by their smaller type, which the OCR gives as longer lines. The Text goes by hexagram (15); the appendixes by Legge's numbering: the 彖 and 象 by hexagram (App. I.15, App. II.15), the 繫辭 by section and chapter (App. III.1.5), the 文言 by hexagram and chapter (App. IV.1.2), the 說卦 by chapter (App. V.5), the 序卦 by part (App. VI.2) and the 雜卦 whole (App. VII). The originals are the Wikisource pages of the hexagrams and of the 易傳.

Sujato's translations of the Core Suttas (SN 56.11, MN 10, MN 118, Snp 1.8, AN 3.65, DN 31), the Sutta Nipāta, the Udāna and the Itivuttaka are split on SuttaCentral's bilara segments, the same segments as the Pali root text. Each block is found, in order, in the run of segments it was made from, and takes that range as its reference (ud1.1:2.1-2.13) and the root text paragraphs it covers as its original. The suttas come from the SuttaCentral API (bilarasuttas/<uid>/sujato). Titles, chapter headings and colophons are flagged is_apparatus.

Plato's works go by Stephanus section (514a), and their Greek is Burnet's, split at the section milestones of the Perseus edition. Jowett's and Burges's translations give no Stephanus numbers, so each is aligned in data/alignments/<work>.json, like the Giles translations, on the section milestones of the Perseus English translation, which are those of the Greek. The anchors were found by matching the words the two English translations share, in order, and setting each speech of a dialogue on the speech it translates. A passage that runs over several sections takes a range (514a-b, 70d-71b). Jowett's introductions, the persons and scene of each dialogue and book heads are flagged is_apparatus.

Aristotle's works go by Bekker column (1094a), and their Greek is Bywater's Ethics and Ross's Metaphysics, Politics and Rhetoric, split at the Bekker page milestones of the Perseus edition. The translations are aligned in data/alignments/<work>.json like Plato's, on the milestones of the Perseus English translation (Rackham, Tredennick, Freese); where Ellis prints a column in brackets ([1256a]) near where the alignment puts it, his mark wins. A passage over several columns takes a range (1094a-b, 1094b-1095a). Ross's Metaphysics is a scan: its page heads and stray letters are flagged is_apparatus, and its footnotes, found by their marks and citations and by sharing no words with Tredennick's translation, are left out by null anchors. Diogenes Laertius and the letters of Epicurus go by book and section (10.124), aligned on Hicks's translation; the Outlines of Pyrrhonism the same way (1.12), on Bury's in First1KGreek, with Mutschmann's Greek from First1KGreek. Long's selection from the Discourses goes by chapter (1.1), the finest unit his translation shares with the Greek, and his Encheiridion by Encheiridion section (Ench. 5), his L covering the Greek 50 and 51. The Enneads go by ennead, treatise and chapter (1.6.9), with Volkmann's Greek from First1KGreek: Guthrie's chapter numbers are read where they agree with Volkmann's, and his treatises 3.5, 3.7, 3.9, 4.3, 6.1, 6.4 and 6.8, which divide some chapters otherwise, are mapped onto Volkmann's by hand; MacKenna's scan is aligned on Guthrie's chapters, and his own chapter numbers win where the OCR reads them a few paragraphs away at most. Burnet's Early Greek Philosophy is left out: it is mostly Burnet's own account, and its fragments have no open Greek edition to take them from.

Ecclesiastes, Job, Proverbs and Psalms go by KJV chapter and verse, and their Hebrew is Sefaria's Miqra according to the Masorah. Where the KJV numbers verses differently, each verse takes the Hebrew one it translates: the Hebrew counts most psalm titles as a verse, or two, which the KJV leaves unnumbered and the Wisdom Context Window leaves out, Ecclesiastes 5:1 is the Hebrew 4:17, and Job 41:1-8 the Hebrew 40:25-32. Pirkei Avot keeps Gorfinkle's saying numbers (2:5), which follow Taylor's, and each saying takes the mishnayot of Sefaria's Torat Emet edition it falls in (2:4), or a range of them (5:8-9). His notes, and the sayings recited before and after each chapter (“All Israel have a portion…”, “Rabbi Chanania…”), are flagged is_apparatus.

Transcriptions

read_passages gives each original a transcription under it, so a reader who doesn't know the script can say it aloud. It is labelled as a pronunciation aid, never as the source. The import computes it into originals.transcription.

Pinyin libraries guess polyphones from modern usage, which is often wrong for classical texts: 不亦說乎 is bù yì yuè hū, not shuō. So every occurrence of a polyphone whose classical reading depends on its sense (說, 樂, 為, 好, 惡, 知, 行, 長, 見, 食…) takes its reading from data/pinyin/<work>.json, keyed by reference and character position. The import fails and lists every occurrence that has no reviewed reading.

pnpm readings:draft [work…]

This drafts the Analects, Laozi and Zhuangzi readings files from 《經典釋文》 (論語音義 and 老子音義, 四部叢刊本 on Chinese Wikisource). Each headword is aligned on the text, and each note is resolved to a 廣韻 sound class through ytenx: 「音X」 is X's class, and 「AB反」 is A's initial with B's rhyme. The script then picks the pinyin reading that is the regular Mandarin outcome of that class. A note marked 下同 carries its reading to later occurrences in the same book. An occurrence with no note takes the usual reading (如字), since 釋文 notes only departures from it. For the Analects, each reading is cross-checked against 朱熹《論語集注》. The Great Learning, the Doctrine of the Mean and Mencius take their readings from 集注 alone, since 釋文 has no 音義 for Mencius: each phonetic note (「去聲」, 「音X」, 「AB反」) is placed in the passage it follows and read the same way, and a note it allows two readings for goes to review. The Zhuangzi takes its readings from 莊子音義 (卷二十六 to 二十八 of the same edition). Its 下同 only carries a reading on to the phrase the note names (「下爲是皆同」) or to its headword, since a 下同 there runs through long chapters over other senses of the same character. The Liezi takes its readings from 殷敬順's 釋文, printed inline with 張湛's notes in the 四庫全書 edition: the two editions are aligned character by character, a note opening with a reading is placed on the words before it, and its 下同 stops with its paragraph, since Giles translates only some of them. The I Ching takes its readings from 周易音義 (卷二, 四部叢刊本), which reads 王弼's arrangement, where each line's 象 follows the line: each hexagram's text is set out in that order before the headwords are aligned on it. The Art of War, Mozi and Xunzi have no 音義 in this pipeline: every occurrence takes the usual reading, reviewed by hand for the Art of War and for senses that context settles in Mozi and Xunzi (惡乎 wū, 所惡 wù, 王天下 wàng).

Each entry records its source and the original note, e.g. "note": "音恱注同", and check when 集注 agrees. Entries where the sources disagree, or where a note couldn't be resolved, carry a todo saying why. The import refuses them until they are reviewed.

The script also lists the notes it skips: a note on a character missing from the polyphone list, whose reading differs from pinyin-pro's. Add such a character to POLYPHONES in src/corpus/transcription/pinyin.ts, with its usual reading in RUZI in src/corpus/transcription/shiwen.ts, and run the script again.

To fix or add a reading, edit the entry: set pinyin, remove todo, add "reviewed": "<your name>", and give your reasoning in note. pnpm readings:draft keeps reviewed entries when it runs again.

pnpm corpus:index

This writes search keywords for each quotable passage, rebuilds the keyword index and embeds the passages, using MISTRAL_API_KEY. Results are cached in CORPUS_CACHE by passage text, so run it again after every import at no extra cost.

Tools

Search is hybrid: an FTS5 keyword index over passage text and keywords, and a vector index over Mistral embeddings, merged with reciprocal rank fusion. When too few passages contain every term, keyword search adds passages that contain any of them, ignoring common English stop words. If the embedding call fails or takes more than 5 seconds, search returns keyword results only and says so. read_passages stops at about 6,000 words. check_quote compares quotes with whitespace and punctuation removed but diacritics kept, through the trigram index on originals and the keyword index on translations. list_concepts matches its filter against a concept's id, name, gloss, tradition, school and domains. get_concept resolves a key passage to a passage id when its work is in the corpus, and lists the others by work as context only, with a 40-word snippet of each. The server sends its quoting rules to the client as MCP instructions.

Endpoints

• POST /mcp: MCP over Streamable HTTP

• GET /health: liveness check

• GET /docs: Swagger UI, outside production

Testing from Claude Code

.mcp.json registers the local server with Claude Code as wisdom. Start it with pnpm start, approve it in /mcp, then ask a question:

/wisdom How to improve global cooperation?

The wisdom skill first restates the question as the human situation underneath it, then answers with search_passages and read_passages only, quoting the originals with their references and its own translations. It may run one web search to understand an unfamiliar term, never as answer content. Ask follow-up questions in the same window. The whole conversation, with the reframed question, every tool call, the ids read and the number of calls per turn, is written to test/output/<NNNNN>-<mon>-<dd>-<question-slug>.md, numbered from 00001, which is git-ignored.

Evaluation

pnpm eval

This runs search_passages on each situation in test/eval/situations.json and reports Recall@10: the share of the passages judged relevant that appear in the first 10 hits, per situation and on average. It needs a built corpus and MISTRAL_API_KEY, so it is not part of CI. Run it before each launch; the target is 0.7.

The set has 88 situations written as a person would ask them, each with 3 to 6 passages judged relevant by hand, at most 3 per work since search returns at most 3 hits per work. A hit counts only if it is the same passage, not another passage of the same reference.

Compatibility

Any MCP client that speaks Streamable HTTP can use the server. Local clients such as Cursor, VS Code, Zed, Gemini CLI or Codex CLI connect to http://localhost:3000/mcp directly. Web apps such as Claude, ChatGPT, Le Chat, Perplexity, Gemini and Grok, and LLM APIs, need a public HTTPS URL. See docs/COMPATIBILITY.md for plans, setup per service, and how to expose the server.

Scripts

Privacy

Every tool call is logged to the usage table in the server's SQLite database:

• the time and the tool called

• the query: the search query, the quote checked, the concept filter or concept id

• the passage ids returned or read, and the number of hits

• the duration, whether search fell back to keywords only, and the embedding tokens billed by Mistral

No IP address, client name or session id is stored. After 30 days, a job that runs daily replaces each query with its SHA-256 hash and keeps the other fields. The log is used to improve search: to review retrieval quality and how many calls it takes to answer a question.

Credits

• Kevin Owocki, for the Wisdom Context Window: the corpus of texts, summaries and concept graph this server searches.

• Chinese Wikisource, Perseus Digital Library, SuttaCentral, Sefaria and the gita/gita dataset, for the original-language texts.

• 陸德明《經典釋文》, 朱熹《四書章句集注》 and 殷敬順's 列子釋文 (四庫全書本), as transcribed on Chinese Wikisource, and ytenx by BYVoid, for the 廣韻 sound classes behind the pinyin readings.

• pinyin-pro, for the base pinyin.

• sqlite-vec by Alex Garcia, for vector search inside SQLite.

• The Model Context Protocol TypeScript SDK.

License

GPL-3.0

Contact

Julien Béranger (GitHub)

• Element: @julienbrg:matrix.org

• Farcaster: julien-

• Telegram: @julienbrg