Репозиторий обучения для начинающих. Никаких рамок. Никаких черных ящиков. Чистый Node.js.

К концу вы создадите работающий MCP-сервер, который можно подключить к Claude Desktop.

** Начните с 01-what-is-mcp/README.md. Этот модуль объясняет, что такое MCP, почему он существует, и мысленная модель, на которой строится каждый следующий модуль.

##Что вы будете строить

Полностью работающий MCP-сервер в простом Node.js, который предоставляет реальные инструменты, точно следует протоколу и подключается к Claude Desktop (или любому клиенту MCP) без изменений.

Вы будете строить его по частям. Каждый модуль отвечает на один вопрос. Ответ на этот вопрос делает следующий вопрос очевидным.

Модуль 06 является вехой tools. Модуль 09 добавляет prompts (командные строки рабочего стола / курсора). Модули 07-11 завершают протокол. Модуль 12 соединяет MCP с агентными рабочими процессами (таможенный цикл + необязательный LangChain).

Репозиторная структура

Одно правило: no npm-зависимости в модулях 01-10 (и модуль 11сервер). Каждый сервер работает с T1. Единственным входом в root package.json является "type": "module" для обеспечения импорта ESM.

MCP from Scratch

A learning repository for complete beginners. No frameworks. No black boxes. Pure Node.js.

By the end you will have built a working MCP server you can connect to Claude Desktop - and you will understand every line of it.

Start with 01-what-is-mcp/README.md. That module explains what MCP is, why it exists, and the mental model every later module builds on.

---

What you will build

A fully working MCP server in plain Node.js that exposes real tools, follows the protocol exactly, and connects to Claude Desktop (or any MCP client) without modification.

You will build it piece by piece. Each module answers one question. The answer to that question makes the next question obvious.

Module 06 is the tools milestone. Module 09 adds prompts (Desktop / Cursor slash commands). Modules 07–11 complete the protocol. Module 12 connects MCP to agent workflows (custom loop + optional LangChain).

---

Repository structure

mcp-from-scratch/
├── README.md                  ← you are here
├── package.json               ← { "type": "module" } - that is all
├── images/                    ← shared diagrams and screenshots used across modules
├── models/                    ← shared GGUF cache reused by modules 11 and 12
│
├── 01-what-is-mcp/
│   ├── README.md
│   └── ANSWERS.md             ← optional self-check answers; this module is docs-only
│
├── 02-json-rpc/
│   ├── README.md
│   ├── run.md
│   └── src/
│       ├── jsonrpc.js         ← encode and decode messages
│       └── dispatcher.js      ← route method calls to handlers
│
├── 03-stdio-transport/
│   ├── README.md
│   ├── run.md
│   └── src/
│       ├── framing.js         ← buffer stdin, emit complete messages
│       ├── server.js          ← reads from stdin, writes to stdout
│       └── client.js          ← spawns server, sends a message, reads reply
│
├── 04-lifecycle/
│   ├── README.md
│   ├── run.md
│   └── src/
│       ├── session.js         ← state machine: CREATED → INITIALIZING → READY → CLOSED
│       ├── server.js          ← handles initialize, sends initialized notification
│       └── client.js          ← sends initialize, waits for handshake to complete
│
├── 05-tools-list/
│   ├── README.md
│   ├── run.md
│   └── src/
│       ├── registry.js        ← store tool definitions
│       ├── server.js          ← handles tools/list
│       └── client.js          ← calls tools/list, prints what it finds
│
├── 06-tools-call/
│   ├── README.md
│   ├── run.md                 ← pick run-local or run-desktop
│   ├── run-local.md           ← full local checklist
│   ├── run-desktop.md         ← full Desktop checklist
│   └── src/
│       ├── server.js          ← handles tools/call, runs the function, returns result
│       ├── client.js          ← calls a tool, prints the result
│       ├── inspector.md       ← MCP Inspector (launch, connect, Claude Desktop limits)