一个面向完全初学者的学习仓库。没有框架。没有黑箱。纯正Node.js。

到最后你会搭建一个能连接Claude Desktop的MCP服务器——你会理解它的每一行内容。

**以01-what-is-mcp/README.md开头。**该模块解释了MCP是什么，为什么存在，以及后续模块的心理模型。

---

你将要建造的

一个完全正常运行的 MCP 服务器，采用纯Node.js，暴露真实工具，严格遵循协议，并且无需修改即可连接 Claude Desktop（或任何 MCP 客户端）。

你将逐步构建它。每个模块回答一个问题。该问题的答案使下一个问题显而易见。

模块06是工具里程碑。模块09增加了提示词（桌面/光标斜杠命令）。模块07–11完成了协议。模块12连接MCP与代理工作流程（自定义循环+可选LangChain）。

---

仓库结构

一条规则：模块01–10（及模块11的服务器）中禁止npm依赖**。每台服务器运行时均为node src/server.js。根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)