How pguso/mcp-from-scratch works
1. Repository shape
- This is a tutorial repo, not a single application. Each numbered folder is a self-contained step that adds one MCP concept on top of the previous one.
- The architecture to diagram is therefore a progression: docs-only concepts first, then protocol core, then transport, lifecycle, capabilities, notifications, sampling, and finally agent integration.
2. Core runtime boundary
- The whole repo is plain Node.js ESM (package.json at root only sets "type": "module").
- Modules 01–10 are dependency-free; they run as simple node src/server.js examples.
- The major boundary throughout is always the same: an MCP client/host process talks to an MCP server process over stdio using JSON-RPC messages.
3. Conceptual introduction
- 01-what-is-mcp/ is documentation-only and establishes the mental model.
- It does not contribute executable architecture, but it defines the terms used by every later module: client, server, tools, resources, prompts, notifications, sampling.
4. Protocol core: JSON-RPC
- 02-json-rpc/ contains the first executable protocol layer.
- src/jsonrpc.js handles message encoding/decoding, and src/dispatcher.js routes method names to handlers.
- This is the foundation for every later module: all higher-level MCP features are just JSON-RPC methods and notifications on top of this message format.
5. Transport: stdio framing
- 03-stdio-transport/ adds the transport boundary between processes.
- framing.js buffers stdin until a full message is available, while server.js reads from stdin and writes to stdout.
- client.js spawns the server process and verifies round-trip communication. This module makes the architecture clearly process-to-process, not in-process.
6. Session lifecycle
- 04-lifecycle/ introduces handshake state.
- session.js models the server/client state machine: CREATED → INITIALIZING → READY → CLOSED.
- server.js handles initialize and sends the initialized notification; client.js waits for the handshake to complete before proceeding.
- Diagram-wise, this is the boundary that separates “transport connected” from “protocol ready.”
7. Tool discovery and execution
- 05-tools-list/ adds capability registration through registry.js and the tools/list method.
- 06-tools-call/ extends that into invocation: the server receives tools/call, executes the tool function, and returns the result.
- This is the first real capability exposed to an MCP client or desktop host, and it is the pattern used for other capability groups later.
8. Error handling
- 07-errors/ clarifies the distinction between JSON-RPC errors and tool-level errors.
- errors.js encodes that boundary: some failures are protocol failures, while others are valid tool results that happen to indicate an application error.
- For architecture diagrams, this module shows that MCP has both transport/protocol error paths and domain-level error paths.
9. Resources and prompts
- 08-resources/ introduces resource definitions and readers via registry.js, resources/list, and resources/read.
- 09-prompts/ adds prompt definitions and resolvers via registry.js, prompts/list, and prompts/get.
- These two modules mirror the tools pattern: a registry on the server side, list/get/read methods, and a client that queries or consumes the capability. They also introduce desktop integrations such as Claude Desktop and Cursor.
10. Server-sent notifications
- 10-notifications/ adds push-style messages from server to client.
- The server emits notifications like tools/list_changed, resources/list_changed, and resources/updated.
- This is an important architectural boundary because it shows MCP is not just request/response; the server can signal state changes asynchronously.
11. Sampling with a local model
- 11-sampling/ adds the sampling flow, where the MCP server sends sampling/createMessage to the client.
- The client hosts a local GGUF model using node-llama-cpp, so model inference lives on the client side, not inside the MCP server.
- This is a key inversion of control: the server requests generation, but the client performs the LLM work. The repo keeps the server dependency-free while allowing local inference in the client.
12. Agents and tool use
- 12-mcp-and-agents/ turns MCP into an agent workflow.
- mcp-session.js is a reusable client session layer for handshake, list, and call operations.
- tool-schema.js converts MCP tool definitions into model-consumable tool schemas, and agent-loop.js demonstrates a plan → act → observe loop.
- The optional langchain-example/ shows the same boundary using LangChain + MCP adapters, while the custom loop keeps the architecture explicit.
13. Shared assets and model cache
- images/ and models/ are shared repo-level assets, not application runtime components.
- The models/ cache matters only for modules 11 and 12, where the local GGUF model can be reused across examples instead of redownloading.
14. How to draw the overall architecture
- At the top level, the repository teaches a layered MCP system:
- documentation and mental model
- JSON-RPC message layer
- stdio transport and framing
- session lifecycle
- capability registries for tools/resources/prompts
- notifications
- client-hosted sampling
- agent orchestration
- The dominant system boundary is always between an MCP host/client and an MCP server, with some advanced flows reversing control so the server asks the client to sample from a local model.
Main entry points: session.js Session · server.js Tools Call · client.js Sampling Client · 01-what-is-mcp What is MCP
Components 24
Docs
Conceptual introduction and shared mental model.
- What is MCP · Documents the MCP mental model and vocabulary.
01-what-is-mcp
Protocol
JSON-RPC message layer and process transport.
- JSON-RPC · Encodes and decodes JSON-RPC messages.
02-json-rpc/src/jsonrpc.js - Dispatcher · Routes JSON-RPC method names to handlers.
02-json-rpc/src/dispatcher.js - Framing · Buffers stdin until a full framed message is available.
03-stdio-transport/src/framing.js - Stdio Server · Reads framed requests from stdin and writes responses to stdout.
03-stdio-transport/src/server.js - Stdio Client · Spawns the server process and verifies round-trip messaging.
03-stdio-transport/src/client.js
Lifecycle
Handshake and readiness state.
- Session · Tracks CREATED, INITIALIZING, READY, and CLOSED states.
04-lifecycle/src/session.js - Lifecycle Server · Handles initialize and emits the initialized notification.
04-lifecycle/src/server.js - Lifecycle Client · Waits for handshake completion before continuing.
04-lifecycle/src/client.js
Capabilities
Server-side registries and MCP methods for tools, resources, and prompts.
- Tools Registry · Registers tool definitions for discovery and execution.
05-tools-list/src/registry.js - Tools List · Implements tools/list to expose available tools.
05-tools-list/src/server.js - Tools Call · Implements tools/call and returns tool results.
06-tools-call/src/server.js - Error Model · Separates JSON-RPC failures from tool-level application errors.
07-errors/src/errors.js - Resources · Registers resources and serves resource reads.
08-resources/src/registry.js - Prompts · Registers prompt templates and prompt resolution.
09-prompts/src/registry.js
Advanced flows
Notifications, sampling inversion, and agent orchestration.
- Notifications · Sends asynchronous list-changed and updated notifications.
10-notifications/src/server.js - Sampling Client · Hosts local model inference and answers sampling requests.
11-sampling/src/client.js - Local LLM · Runs GGUF inference on the client side via node-llama-cpp.
11-sampling/src/llm.js - Agent Loop · Implements plan-act-observe tool use around MCP.
12-mcp-and-agents/src/agent-loop.js - MCP Session · Reusable handshake, list, and call layer for agents.
12-mcp-and-agents/src/mcp-session.js - Tool Schema · Converts MCP tools into model-consumable tool schemas.
12-mcp-and-agents/src/tool-schema.js - LangChain Example · Alternative agent integration using LangChain MCP adapters.
12-mcp-and-agents/langchain-example/agent.mjs
Connections 22
- ESM Root → What is MCP: sets module mode · The repo is organized as plain Node.js ESM examples.
- What is MCP → JSON-RPC: introduces terms · Defines the client/server and capability vocabulary used later.
- JSON-RPC → Dispatcher: routes through · Method routing sits on top of JSON-RPC message handling.
- Dispatcher → Framing: flows over · Higher-level protocol methods are carried over framed stdio messages.
- Framing → Stdio Server: connects · The server reads and writes framed messages on stdin/stdout.
- Stdio Server → Stdio Client: round-trips with · The client spawns the server and verifies process-to-process communication.
- Stdio Client → Session: awaits · Later examples add handshake state before normal protocol use.
- Session → Lifecycle Server: coordinates · The server transitions from initialize to ready.
- Session → Lifecycle Client: coordinates · The client waits until the session is ready.
- Lifecycle Server → Tools Registry: exposes · Capability registration begins with tool discovery.
- Tools Registry → Tools List: powers · The registry feeds the tools/list method.
- Tools List → Tools Call: extends to · Tool discovery becomes tool invocation in the next step.
- Tools Call → Error Model: distinguishes · Protocol errors are separated from valid tool errors.
- Tools Call → Resources: mirrors pattern · Resources reuse the registry/list/read server-side structure.
- Resources → Prompts: mirrors pattern · Prompts reuse the same registry plus list/get shape.
- Prompts → Notifications: adds push · Notifications let the server signal state changes asynchronously.
- Notifications → Sampling Client: inverts control · The server can request model generation from the client host.
- Sampling Client → Local LLM: hosts · Local inference lives on the client side, not in the MCP server.
- Sampling Client → MCP Session: reuses · Agent flows build on a reusable session layer.
- MCP Session → Tool Schema: adapts into · Tool metadata is converted for model/tool calling.
- Tool Schema → Agent Loop: drives · Schemas feed the plan-act-observe agent loop.
- Agent Loop → LangChain Example: parallels · A second integration shows the same MCP boundary through LangChain.