A living, multilingual, page‑flipping illustrated book about the Model Context Protocol (MCP) — grown from notes, transcripts, and everything I learn along the way.
Written by Kardel Rüveyda Çetin
Read it here: https://kardelruveyda.github.io/mcp-codex/
The site is automatically rebuilt and republished on every push to main via GitHub Actions + GitHub Pages.
The MCP Codex is a small Next.js app that turns everything I'm learning about the Model Context Protocol into a beautiful, parchment‑styled flip‑book.
- Designed for anyone who wants to understand what MCP is and how to use it — no prior background needed.
- Concepts are explained at a friendly level, with fun analogies, callouts, and Mermaid diagrams for every important idea.
- Available in 25 languages, with automatic fallback to English when a translation is still pending.
- No accounts. No tracking. No progress saved. Just pages to turn.
| # | Title | Status |
|---|---|---|
| 1 | What on Earth is MCP? | ✅ EN + TR full · titles in 11 languages |
| 2 | But… don't we already have APIs? | ✅ EN + TR full · titles in 11 languages |
| … | more coming as I keep learning | 🌱 |
Each chapter is a sequence of pages defined as typed content blocks (h2, h3, p, ul, tip, fun, note, mermaid).
🇬🇧 English · 🇹🇷 Türkçe · 🇩🇪 Deutsch · 🇪🇸 Español · 🇫🇷 Français · 🇮🇹 Italiano · 🇵🇹 Português · 🇳🇱 Nederlands · 🇵🇱 Polski · 🇷🇺 Русский · 🇺🇦 Українська · 🇬🇷 Ελληνικά · 🇸🇪 Svenska · 🇷🇴 Română · 🇨🇿 Čeština · 🇭🇺 Magyar · 🇮🇩 Bahasa Indonesia · 🇻🇳 Tiếng Việt · 🇮🇳 हिन्दी · 🇨🇳 中文 · 🇯🇵 日本語 · 🇰🇷 한국어 · 🇸🇦 العربية · 🇮🇱 עברית · 🇮🇷 فارسی
English is the source. Pages without a translation gracefully fall back to English and show a small notice in the reader's chosen language.
- 📖 Real page‑flip animation — drag a corner of a page to turn it.
- 🔍 Click any diagram to enlarge it full‑screen (✕ Close or
Escto exit, mouse wheel to zoom). - 🌐 Language dropdown with real flag images (works on every OS).
- 🔠 Font size controls (
A−/A+/RESET, 12–28 px). - ↩️ RTL aware for Arabic, Hebrew and Persian.
- ⚡ Static site — fast, cacheable, no backend.
npm install
npm run devThen open http://localhost:3000 → OPEN THE BOOK.
mcp-codex/
├── app/
│ ├── layout.tsx # HTML shell + metadata
│ ├── page.tsx # Landing / cover page
│ ├── book/page.tsx # The flip‑book reader route
│ └── globals.css # Parchment styling, lightbox, etc.
├── components/
│ ├── BookViewer.tsx # react-pageflip + dropdown + font controls
│ └── Mermaid.tsx # Inline diagram + portal lightbox
├── content/
│ └── chapters.ts # All chapters in all languages (single source of truth)
├── .github/workflows/
│ └── deploy.yml # Static export + GitHub Pages deploy
└── next.config.js # output: "export", basePath for Pages
Open content/chapters.ts and push a new object into chapters. Each page's body is keyed by language — only en is required, everything else is optional:
{
id: 3,
title: { en: "Chapter title", tr: "Bölüm başlığı" },
tagline: { en: "One-line hook", tr: "Tek satır kanca" },
pages: [
{
body: {
en: [
{ t: "h2", v: "Section heading" },
{ t: "p", v: "A friendly paragraph." },
{ t: "ul", v: ["bullet one", "bullet two"] },
{ t: "tip", v: "A handy little tip." },
{ t: "mermaid", v: `flowchart LR; A-->B;` },
],
tr: [ /* same shape, in Turkish */ ],
},
},
],
}- Append a new entry to the
LANGUAGESarray in content/chapters.ts with an ISO country code for the flag. - Add a matching block of UI strings to the
UIobject. - (Optional) Add per‑page translations to any chapter you want covered.
Every push to main triggers .github/workflows/deploy.yml:
npm cinpm run build→ static export intoout/- Upload
out/as a Pages artifact - Publish to https://kardelruveyda.github.io/mcp-codex/
- Next.js 14 (App Router · static export)
- Tailwind CSS
- react‑pageflip for the leafing animation
- Mermaid for the diagrams
- Flag images from flagcdn.com
Contributions are very welcome — translations, typo fixes, new chapters, even a single sentence rewrite. The book lives or dies by being clear and friendly, so every set of fresh eyes helps.
- 🌐 A translation of an existing page (the most useful single thing you can do).
- 📝 A fix for a typo, awkward sentence, or unclear explanation.
- 🌱 A new chapter based on a video / article you found useful (see content rules below).
- 🎨 Visual / UX polish — better diagrams, better styles, accessibility improvements.
- 🐛 Bug reports via GitHub Issues.
- Fork this repo, then clone your fork.
- Create a branch:
git checkout -b my-change
- Install and run locally to see your edit live:
npm install npm run dev
- Edit the right file (see below), check it in the browser, commit, push, then open a Pull Request against
main.
| You want to… | Edit |
|---|---|
| Translate a page or fix a sentence | content/chapters.ts |
| Add a whole new chapter | content/chapters.ts (push into chapters) |
| Add a brand new language | content/chapters.ts (LANGUAGES + UI) |
| Change the reader UI | components/BookViewer.tsx |
| Change the cover / landing page | app/page.tsx |
| Change styling | app/globals.css |
Open content/chapters.ts, find the page you want to translate, and add your language key next to en. Example — translating Chapter 1, page 1 into German:
body: {
en: [ /* …existing… */ ],
tr: [ /* …existing… */ ],
de: [
{ t: "h2", v: "Es war einmal ein KI-Agent…" },
{ t: "p", v: "Stell dir vor, du hast einen klugen KI-Assistenten gebaut…" },
// …same block types in the same order
],
}Rules of thumb for translations:
- Keep the same block order as the English version so diagrams stay in the same spot.
- Mermaid diagrams are kept language‑neutral (English labels) on purpose — please don't translate inside them.
- Aim for a natural, friendly tone at roughly B1 reading level. It's a book for humans, not a spec.
If you want to add a chapter from your own source (video, article, talk), please follow these content rules — they keep the book legally clean and pleasant to read:
- ✅ Take concepts and structure from your source.
- ❌ Do not copy sentences verbatim. Paraphrase in your own words.
- 🔄 Replace named examples from the source with your own original examples (different APIs, different tool names, different scenarios). This avoids both plagiarism and "I've read this exact thing before" fatigue.
- 🎭 Keep it warm and a little playful — use the
tip/fun/notecallouts, not just walls of text. - 📐 Add at least one Mermaid diagram per chapter when it helps.
Use this skeleton:
{
id: 99, // next free number
title: { en: "Chapter title", tr: "Bölüm başlığı" },
tagline: { en: "One-line hook", tr: "Tek satır kanca" },
pages: [
{
body: {
en: [
{ t: "h2", v: "Section heading" },
{ t: "p", v: "A friendly paragraph." },
{ t: "ul", v: ["bullet one", "bullet two"] },
{ t: "tip", v: "A handy little tip." },
{ t: "mermaid", v: `flowchart LR; A-->B;` },
],
},
},
],
}Only en is required. Any other language is optional and will fall back to English automatically.
- Append a new entry to the
LANGUAGESarray in content/chapters.ts with an ISO country code for the flag:{ code: "no", label: "Norsk", cc: "no", dir: "ltr" as const },
- Add a matching block to the
UIobject with translations of every key. - Optionally translate any pages you want covered. Untranslated pages fall back to English.
Before opening a PR, please:
-
npm run buildsucceeds locally (catches type and content errors). - The page renders correctly in the browser (open it, flip to it, make sure diagrams and callouts look right).
- You followed the content rules above for any new prose.
- The PR description briefly explains what changed and why (one or two sentences is fine).
Be kind, be curious, assume good intent. That's it.
MIT for the code. The book text and diagrams are © Kardel Rüveyda Çetin — feel free to share with attribution.