{"id":51061834,"url":"https://github.com/kardelruveyda/mcp-codex","last_synced_at":"2026-06-23T03:01:11.059Z","repository":{"id":358529496,"uuid":"1241742971","full_name":"KardelRuveyda/mcp-codex","owner":"KardelRuveyda","description":"Read it live: https://kardelruveyda.github.io/mcp-codex/ — A multilingual (25 languages), page-flipping illustrated book about the Model Context Protocol (MCP). By Kardel Rüveyda Çetin.","archived":false,"fork":false,"pushed_at":"2026-05-17T19:33:16.000Z","size":96,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-17T21:40:04.401Z","etag":null,"topics":["ai-agents","ebook","education","i18n","interactive-book","learning-resource","llm","mcp","mermaid","model-context-protocol","multilingual","nextjs","tailwindcss","typescript"],"latest_commit_sha":null,"homepage":"https://kardelruveyda.github.io/mcp-codex/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/KardelRuveyda.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-17T19:01:41.000Z","updated_at":"2026-05-17T19:35:48.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/KardelRuveyda/mcp-codex","commit_stats":null,"previous_names":["kardelruveyda/mcp-codex"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/KardelRuveyda/mcp-codex","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KardelRuveyda%2Fmcp-codex","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KardelRuveyda%2Fmcp-codex/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KardelRuveyda%2Fmcp-codex/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KardelRuveyda%2Fmcp-codex/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/KardelRuveyda","download_url":"https://codeload.github.com/KardelRuveyda/mcp-codex/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KardelRuveyda%2Fmcp-codex/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34673437,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-23T02:00:07.161Z","response_time":65,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","ebook","education","i18n","interactive-book","learning-resource","llm","mcp","mermaid","model-context-protocol","multilingual","nextjs","tailwindcss","typescript"],"created_at":"2026-06-23T03:01:08.835Z","updated_at":"2026-06-23T03:01:11.047Z","avatar_url":"https://github.com/KardelRuveyda.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# The MCP Codex 📖✨\n\n\u003e A living, multilingual, page‑flipping illustrated book about the **Model Context Protocol (MCP)** — grown from notes, transcripts, and everything I learn along the way.\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://kardelruveyda.github.io/mcp-codex/\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/READ%20THE%20BOOK-LIVE-6b1e2b?style=for-the-badge\u0026logo=readme\u0026logoColor=f5ecd7\" alt=\"Read the book\" /\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cem\u003eWritten by \u003cstrong\u003eKardel Rüveyda Çetin\u003c/strong\u003e\u003c/em\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg alt=\"Next.js\" src=\"https://img.shields.io/badge/Next.js-14-black?logo=next.js\" /\u003e\n  \u003cimg alt=\"TypeScript\" src=\"https://img.shields.io/badge/TypeScript-5-3178c6?logo=typescript\u0026logoColor=white\" /\u003e\n  \u003cimg alt=\"Tailwind\" src=\"https://img.shields.io/badge/Tailwind-3-38bdf8?logo=tailwindcss\u0026logoColor=white\" /\u003e\n  \u003cimg alt=\"Languages\" src=\"https://img.shields.io/badge/Languages-25-b8860b\" /\u003e\n  \u003cimg alt=\"License: MIT\" src=\"https://img.shields.io/badge/License-MIT-green\" /\u003e\n\u003c/p\u003e\n\n---\n\n## 🌐 Live\n\n**Read it here:** \u003chttps://kardelruveyda.github.io/mcp-codex/\u003e\n\nThe site is automatically rebuilt and republished on every push to `main` via GitHub Actions + GitHub Pages.\n\n---\n\n## ✨ What is this?\n\n**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.\n\n- Designed for **anyone who wants to understand what MCP is and how to use it** — no prior background needed.\n- Concepts are explained at a friendly level, with **fun analogies, callouts, and Mermaid diagrams** for every important idea.\n- Available in **25 languages**, with automatic fallback to English when a translation is still pending.\n- **No accounts. No tracking. No progress saved.** Just pages to turn.\n\n---\n\n## 📑 Chapters so far\n\n| # | Title | Status |\n|---|---|---|\n| 1 | What on Earth is MCP? | ✅ EN + TR full · titles in 11 languages |\n| 2 | But… don't we already have APIs? | ✅ EN + TR full · titles in 11 languages |\n| … | _more coming as I keep learning_ | 🌱 |\n\nEach chapter is a sequence of pages defined as typed content blocks (`h2`, `h3`, `p`, `ul`, `tip`, `fun`, `note`, `mermaid`).\n\n---\n\n## 🌍 Languages\n\n🇬🇧 English · 🇹🇷 Türkçe · 🇩🇪 Deutsch · 🇪🇸 Español · 🇫🇷 Français · 🇮🇹 Italiano · 🇵🇹 Português ·\n🇳🇱 Nederlands · 🇵🇱 Polski · 🇷🇺 Русский · 🇺🇦 Українська · 🇬🇷 Ελληνικά · 🇸🇪 Svenska ·\n🇷🇴 Română · 🇨🇿 Čeština · 🇭🇺 Magyar · 🇮🇩 Bahasa Indonesia · 🇻🇳 Tiếng Việt · 🇮🇳 हिन्दी ·\n🇨🇳 中文 · 🇯🇵 日本語 · 🇰🇷 한국어 · 🇸🇦 العربية · 🇮🇱 עברית · 🇮🇷 فارسی\n\nEnglish is the source. Pages without a translation gracefully fall back to English and show a small notice in the reader's chosen language.\n\n---\n\n## 🎛️ Reader features\n\n- 📖 **Real page‑flip animation** — drag a corner of a page to turn it.\n- 🔍 **Click any diagram** to enlarge it full‑screen (✕ Close or `Esc` to exit, mouse wheel to zoom).\n- 🌐 **Language dropdown** with real flag images (works on every OS).\n- 🔠 **Font size controls** (`A−` / `A+` / `RESET`, 12–28 px).\n- ↩️ **RTL aware** for Arabic, Hebrew and Persian.\n- ⚡ **Static site** — fast, cacheable, no backend.\n\n---\n\n## 🛠️ Run it locally\n\n```bash\nnpm install\nnpm run dev\n```\n\nThen open \u003chttp://localhost:3000\u003e → **OPEN THE BOOK**.\n\n---\n\n## 🗂️ Project structure\n\n```\nmcp-codex/\n├── app/\n│   ├── layout.tsx           # HTML shell + metadata\n│   ├── page.tsx             # Landing / cover page\n│   ├── book/page.tsx        # The flip‑book reader route\n│   └── globals.css          # Parchment styling, lightbox, etc.\n├── components/\n│   ├── BookViewer.tsx       # react-pageflip + dropdown + font controls\n│   └── Mermaid.tsx          # Inline diagram + portal lightbox\n├── content/\n│   └── chapters.ts          # All chapters in all languages (single source of truth)\n├── .github/workflows/\n│   └── deploy.yml           # Static export + GitHub Pages deploy\n└── next.config.js           # output: \"export\", basePath for Pages\n```\n\n---\n\n## ➕ Adding a new chapter\n\nOpen [content/chapters.ts](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:\n\n```ts\n{\n  id: 3,\n  title:   { en: \"Chapter title\", tr: \"Bölüm başlığı\" },\n  tagline: { en: \"One-line hook\", tr: \"Tek satır kanca\" },\n  pages: [\n    {\n      body: {\n        en: [\n          { t: \"h2\", v: \"Section heading\" },\n          { t: \"p\",  v: \"A friendly paragraph.\" },\n          { t: \"ul\", v: [\"bullet one\", \"bullet two\"] },\n          { t: \"tip\", v: \"A handy little tip.\" },\n          { t: \"mermaid\", v: `flowchart LR; A--\u003eB;` },\n        ],\n        tr: [ /* same shape, in Turkish */ ],\n      },\n    },\n  ],\n}\n```\n\n---\n\n## 🌐 Adding a new language\n\n1. Append a new entry to the `LANGUAGES` array in [content/chapters.ts](content/chapters.ts) with an ISO country code for the flag.\n2. Add a matching block of UI strings to the `UI` object.\n3. (Optional) Add per‑page translations to any chapter you want covered.\n\n---\n\n## 🚀 How it deploys\n\nEvery push to `main` triggers [.github/workflows/deploy.yml](.github/workflows/deploy.yml):\n\n1. `npm ci`\n2. `npm run build` → static export into `out/`\n3. Upload `out/` as a Pages artifact\n4. Publish to \u003chttps://kardelruveyda.github.io/mcp-codex/\u003e\n\n---\n\n## 🪄 Tech\n\n- [Next.js 14](https://nextjs.org/) (App Router · static export)\n- [Tailwind CSS](https://tailwindcss.com/)\n- [react‑pageflip](https://www.npmjs.com/package/react-pageflip) for the leafing animation\n- [Mermaid](https://mermaid.js.org/) for the diagrams\n- Flag images from [flagcdn.com](https://flagcdn.com)\n\n---\n\n## 🤝 Contributing\n\nContributions 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.\n\n### What you can contribute\n\n- 🌐 **A translation** of an existing page (the most useful single thing you can do).\n- 📝 **A fix** for a typo, awkward sentence, or unclear explanation.\n- 🌱 **A new chapter** based on a video / article you found useful (see content rules below).\n- 🎨 **Visual / UX polish** — better diagrams, better styles, accessibility improvements.\n- 🐛 **Bug reports** via [GitHub Issues](https://github.com/KardelRuveyda/mcp-codex/issues).\n\n### Quick start (for any change)\n\n1. **Fork** this repo, then clone your fork.\n2. Create a branch:\n   ```bash\n   git checkout -b my-change\n   ```\n3. Install and run locally to see your edit live:\n   ```bash\n   npm install\n   npm run dev\n   ```\n4. Edit the right file (see below), check it in the browser, commit, push, then open a **Pull Request** against `main`.\n\n### Where things live\n\n| You want to… | Edit |\n|---|---|\n| Translate a page or fix a sentence | [content/chapters.ts](content/chapters.ts) |\n| Add a whole new chapter | [content/chapters.ts](content/chapters.ts) (push into `chapters`) |\n| Add a brand new language | [content/chapters.ts](content/chapters.ts) (`LANGUAGES` + `UI`) |\n| Change the reader UI | [components/BookViewer.tsx](components/BookViewer.tsx) |\n| Change the cover / landing page | [app/page.tsx](app/page.tsx) |\n| Change styling | [app/globals.css](app/globals.css) |\n\n### Adding a translation (the most common case)\n\nOpen [content/chapters.ts](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:\n\n```ts\nbody: {\n  en: [ /* …existing… */ ],\n  tr: [ /* …existing… */ ],\n  de: [\n    { t: \"h2\", v: \"Es war einmal ein KI-Agent…\" },\n    { t: \"p\",  v: \"Stell dir vor, du hast einen klugen KI-Assistenten gebaut…\" },\n    // …same block types in the same order\n  ],\n}\n```\n\nRules of thumb for translations:\n\n- Keep the **same block order** as the English version so diagrams stay in the same spot.\n- Mermaid diagrams are kept **language‑neutral** (English labels) on purpose — please don't translate inside them.\n- Aim for a natural, friendly tone at roughly **B1 reading level**. It's a book for humans, not a spec.\n\n### Adding a new chapter\n\nIf 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:\n\n- ✅ Take **concepts and structure** from your source.\n- ❌ **Do not** copy sentences verbatim. Paraphrase in your own words.\n- 🔄 **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.\n- 🎭 Keep it warm and a little playful — use the `tip` / `fun` / `note` callouts, not just walls of text.\n- 📐 Add at least one Mermaid diagram per chapter when it helps.\n\nUse this skeleton:\n\n```ts\n{\n  id: 99, // next free number\n  title:   { en: \"Chapter title\", tr: \"Bölüm başlığı\" },\n  tagline: { en: \"One-line hook\", tr: \"Tek satır kanca\" },\n  pages: [\n    {\n      body: {\n        en: [\n          { t: \"h2\", v: \"Section heading\" },\n          { t: \"p\",  v: \"A friendly paragraph.\" },\n          { t: \"ul\", v: [\"bullet one\", \"bullet two\"] },\n          { t: \"tip\", v: \"A handy little tip.\" },\n          { t: \"mermaid\", v: `flowchart LR; A--\u003eB;` },\n        ],\n      },\n    },\n  ],\n}\n```\n\nOnly `en` is required. Any other language is optional and will fall back to English automatically.\n\n### Adding a brand new language\n\n1. Append a new entry to the `LANGUAGES` array in [content/chapters.ts](content/chapters.ts) with an ISO country code for the flag:\n   ```ts\n   { code: \"no\", label: \"Norsk\", cc: \"no\", dir: \"ltr\" as const },\n   ```\n2. Add a matching block to the `UI` object with translations of every key.\n3. Optionally translate any pages you want covered. Untranslated pages fall back to English.\n\n### Pull request checklist\n\nBefore opening a PR, please:\n\n- [ ] `npm run build` succeeds locally (catches type and content errors).\n- [ ] The page renders correctly in the browser (open it, flip to it, make sure diagrams and callouts look right).\n- [ ] You followed the **content rules** above for any new prose.\n- [ ] The PR description briefly explains _what_ changed and _why_ (one or two sentences is fine).\n\n### Code of conduct\n\nBe kind, be curious, assume good intent. That's it.\n\n---\n\n## 📜 License\n\n**MIT** for the code. The book text and diagrams are © Kardel Rüveyda Çetin — feel free to share with attribution.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkardelruveyda%2Fmcp-codex","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkardelruveyda%2Fmcp-codex","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkardelruveyda%2Fmcp-codex/lists"}