# pguso/mcp-from-scratch architecture

> Architecture diagram of the GitHub repository pguso/mcp-from-scratch, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pguso/mcp-from-scratch
- Repository: https://github.com/pguso/mcp-from-scratch

## Overview

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: [`04-lifecycle/src/session.js`](https://github.com/pguso/mcp-from-scratch/blob/main/04-lifecycle/src/session.js) (Session), [`06-tools-call/src/server.js`](https://github.com/pguso/mcp-from-scratch/blob/main/06-tools-call/src/server.js) (Tools Call), [`11-sampling/src/client.js`](https://github.com/pguso/mcp-from-scratch/blob/main/11-sampling/src/client.js) (Sampling Client), [`01-what-is-mcp`](https://github.com/pguso/mcp-from-scratch/tree/main/01-what-is-mcp) (What is MCP)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_docs["Docs"]
  node_what_is_mcp["What is MCP<br/>docs step"]
end

subgraph group_protocol["Protocol"]
  node_jsonrpc_core["JSON-RPC<br/>protocol layer<br/>[jsonrpc.js]"]
  node_dispatcher["Dispatcher<br/>method router<br/>[dispatcher.js]"]
  node_framing["Framing<br/>stdio transport<br/>[framing.js]"]
  node_stdio_server["Stdio Server<br/>process endpoint<br/>[server.js]"]
  node_stdio_client["Stdio Client<br/>process client<br/>[client.js]"]
end

subgraph group_lifecycle["Lifecycle"]
  node_session(("Session<br/>state machine<br/>[session.js]"))
  node_lifecycle_server["Lifecycle Server<br/>mcp server<br/>[server.js]"]
  node_lifecycle_client["Lifecycle Client<br/>mcp client<br/>[client.js]"]
end

subgraph group_capabilities["Capabilities"]
  node_tools_registry[("Tools Registry<br/>capability registry<br/>[registry.js]")]
  node_tools_list_server["Tools List<br/>mcp method<br/>[server.js]"]
  node_tools_call_server["Tools Call<br/>mcp method<br/>[server.js]"]
  node_error_model["Error Model<br/>error boundary<br/>[errors.js]"]
  node_resources_registry[("Resources<br/>capability registry<br/>[registry.js]")]
  node_prompts_registry[("Prompts<br/>capability registry<br/>[registry.js]")]
end

subgraph group_advanced["Advanced flows"]
  node_notifications_server["Notifications<br/>push messages<br/>[server.js]"]
  node_sampling_client["Sampling Client<br/>host runtime<br/>[client.js]"]
  node_llm_local{{"Local LLM<br/>model runtime<br/>[llm.js]"}}
  node_agent_loop(("Agent Loop<br/>orchestration<br/>[agent-loop.js]"))
  node_mcp_session["MCP Session<br/>client session<br/>[mcp-session.js]"]
  node_tool_schema["Tool Schema<br/>adapter<br/>[tool-schema.js]"]
  node_langchain_example["LangChain Example<br/>integration example<br/>[agent.mjs]"]
end

subgraph group_shared["Shared"]
  node_root_esm["ESM Root<br/>package setting<br/>[package.json]"]
  node_images_assets["Diagrams<br/>shared assets"]
end

node_root_esm -->|"sets module mode"| node_what_is_mcp
node_what_is_mcp -->|"introduces terms"| node_jsonrpc_core
node_jsonrpc_core -->|"routes through"| node_dispatcher
node_dispatcher -->|"flows over"| node_framing
node_framing -->|"connects"| node_stdio_server
node_stdio_server -->|"round-trips with"| node_stdio_client
node_stdio_client -->|"awaits"| node_session
node_session -->|"coordinates"| node_lifecycle_server
node_session -->|"coordinates"| node_lifecycle_client
node_lifecycle_server -->|"exposes"| node_tools_registry
node_tools_registry -->|"powers"| node_tools_list_server
node_tools_list_server -->|"extends to"| node_tools_call_server
node_tools_call_server -->|"distinguishes"| node_error_model
node_tools_call_server -->|"mirrors pattern"| node_resources_registry
node_resources_registry -->|"mirrors pattern"| node_prompts_registry
node_prompts_registry -->|"adds push"| node_notifications_server
node_notifications_server -->|"inverts control"| node_sampling_client
node_sampling_client -->|"hosts"| node_llm_local
node_sampling_client -->|"reuses"| node_mcp_session
node_mcp_session -->|"adapts into"| node_tool_schema
node_tool_schema -->|"drives"| node_agent_loop
node_agent_loop -.->|"parallels"| node_langchain_example

click node_root_esm "https://github.com/pguso/mcp-from-scratch/blob/main/package.json"
click node_images_assets "https://github.com/pguso/mcp-from-scratch/tree/main/images"
click node_what_is_mcp "https://github.com/pguso/mcp-from-scratch/tree/main/01-what-is-mcp"
click node_jsonrpc_core "https://github.com/pguso/mcp-from-scratch/blob/main/02-json-rpc/src/jsonrpc.js"
click node_dispatcher "https://github.com/pguso/mcp-from-scratch/blob/main/02-json-rpc/src/dispatcher.js"
click node_framing "https://github.com/pguso/mcp-from-scratch/blob/main/03-stdio-transport/src/framing.js"
click node_stdio_server "https://github.com/pguso/mcp-from-scratch/blob/main/03-stdio-transport/src/server.js"
click node_stdio_client "https://github.com/pguso/mcp-from-scratch/blob/main/03-stdio-transport/src/client.js"
click node_session "https://github.com/pguso/mcp-from-scratch/blob/main/04-lifecycle/src/session.js"
click node_lifecycle_server "https://github.com/pguso/mcp-from-scratch/blob/main/04-lifecycle/src/server.js"
click node_lifecycle_client "https://github.com/pguso/mcp-from-scratch/blob/main/04-lifecycle/src/client.js"
click node_tools_registry "https://github.com/pguso/mcp-from-scratch/blob/main/05-tools-list/src/registry.js"
click node_tools_list_server "https://github.com/pguso/mcp-from-scratch/blob/main/05-tools-list/src/server.js"
click node_tools_call_server "https://github.com/pguso/mcp-from-scratch/blob/main/06-tools-call/src/server.js"
click node_error_model "https://github.com/pguso/mcp-from-scratch/blob/main/07-errors/src/errors.js"
click node_resources_registry "https://github.com/pguso/mcp-from-scratch/blob/main/08-resources/src/registry.js"
click node_prompts_registry "https://github.com/pguso/mcp-from-scratch/blob/main/09-prompts/src/registry.js"
click node_notifications_server "https://github.com/pguso/mcp-from-scratch/blob/main/10-notifications/src/server.js"
click node_sampling_client "https://github.com/pguso/mcp-from-scratch/blob/main/11-sampling/src/client.js"
click node_llm_local "https://github.com/pguso/mcp-from-scratch/blob/main/11-sampling/src/llm.js"
click node_agent_loop "https://github.com/pguso/mcp-from-scratch/blob/main/12-mcp-and-agents/src/agent-loop.js"
click node_mcp_session "https://github.com/pguso/mcp-from-scratch/blob/main/12-mcp-and-agents/src/mcp-session.js"
click node_tool_schema "https://github.com/pguso/mcp-from-scratch/blob/main/12-mcp-and-agents/src/tool-schema.js"
click node_langchain_example "https://github.com/pguso/mcp-from-scratch/blob/main/12-mcp-and-agents/langchain-example/agent.mjs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_what_is_mcp toneBlue
class node_jsonrpc_core,node_dispatcher,node_framing,node_stdio_server,node_stdio_client toneAmber
class node_session,node_lifecycle_server,node_lifecycle_client toneMint
class node_tools_registry,node_tools_list_server,node_tools_call_server,node_error_model,node_resources_registry,node_prompts_registry toneRose
class node_notifications_server,node_sampling_client,node_llm_local,node_agent_loop,node_mcp_session,node_tool_schema,node_langchain_example toneIndigo
class node_root_esm,node_images_assets toneTeal
```

## Components

### Docs

Conceptual introduction and shared mental model.

- [What is MCP](https://github.com/pguso/mcp-from-scratch/tree/main/01-what-is-mcp): docs step · Documents the MCP mental model and vocabulary. · `01-what-is-mcp`

### Protocol

JSON-RPC message layer and process transport.

- [JSON-RPC](https://github.com/pguso/mcp-from-scratch/blob/main/02-json-rpc/src/jsonrpc.js): protocol layer · Encodes and decodes JSON-RPC messages. · `02-json-rpc/src/jsonrpc.js`
- [Dispatcher](https://github.com/pguso/mcp-from-scratch/blob/main/02-json-rpc/src/dispatcher.js): method router · Routes JSON-RPC method names to handlers. · `02-json-rpc/src/dispatcher.js`
- [Framing](https://github.com/pguso/mcp-from-scratch/blob/main/03-stdio-transport/src/framing.js): stdio transport · Buffers stdin until a full framed message is available. · `03-stdio-transport/src/framing.js`
- [Stdio Server](https://github.com/pguso/mcp-from-scratch/blob/main/03-stdio-transport/src/server.js): process endpoint · Reads framed requests from stdin and writes responses to stdout. · `03-stdio-transport/src/server.js`
- [Stdio Client](https://github.com/pguso/mcp-from-scratch/blob/main/03-stdio-transport/src/client.js): process client · Spawns the server process and verifies round-trip messaging. · `03-stdio-transport/src/client.js`

### Lifecycle

Handshake and readiness state.

- [Session](https://github.com/pguso/mcp-from-scratch/blob/main/04-lifecycle/src/session.js): state machine · Tracks CREATED, INITIALIZING, READY, and CLOSED states. · `04-lifecycle/src/session.js`
- [Lifecycle Server](https://github.com/pguso/mcp-from-scratch/blob/main/04-lifecycle/src/server.js): mcp server · Handles initialize and emits the initialized notification. · `04-lifecycle/src/server.js`
- [Lifecycle Client](https://github.com/pguso/mcp-from-scratch/blob/main/04-lifecycle/src/client.js): mcp 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](https://github.com/pguso/mcp-from-scratch/blob/main/05-tools-list/src/registry.js): capability registry · Registers tool definitions for discovery and execution. · `05-tools-list/src/registry.js`
- [Tools List](https://github.com/pguso/mcp-from-scratch/blob/main/05-tools-list/src/server.js): mcp method · Implements tools/list to expose available tools. · `05-tools-list/src/server.js`
- [Tools Call](https://github.com/pguso/mcp-from-scratch/blob/main/06-tools-call/src/server.js): mcp method · Implements tools/call and returns tool results. · `06-tools-call/src/server.js`
- [Error Model](https://github.com/pguso/mcp-from-scratch/blob/main/07-errors/src/errors.js): error boundary · Separates JSON-RPC failures from tool-level application errors. · `07-errors/src/errors.js`
- [Resources](https://github.com/pguso/mcp-from-scratch/blob/main/08-resources/src/registry.js): capability registry · Registers resources and serves resource reads. · `08-resources/src/registry.js`
- [Prompts](https://github.com/pguso/mcp-from-scratch/blob/main/09-prompts/src/registry.js): capability registry · Registers prompt templates and prompt resolution. · `09-prompts/src/registry.js`

### Advanced flows

Notifications, sampling inversion, and agent orchestration.

- [Notifications](https://github.com/pguso/mcp-from-scratch/blob/main/10-notifications/src/server.js): push messages · Sends asynchronous list-changed and updated notifications. · `10-notifications/src/server.js`
- [Sampling Client](https://github.com/pguso/mcp-from-scratch/blob/main/11-sampling/src/client.js): host runtime · Hosts local model inference and answers sampling requests. · `11-sampling/src/client.js`
- [Local LLM](https://github.com/pguso/mcp-from-scratch/blob/main/11-sampling/src/llm.js): model runtime · Runs GGUF inference on the client side via node-llama-cpp. · `11-sampling/src/llm.js`
- [Agent Loop](https://github.com/pguso/mcp-from-scratch/blob/main/12-mcp-and-agents/src/agent-loop.js): orchestration · Implements plan-act-observe tool use around MCP. · `12-mcp-and-agents/src/agent-loop.js`
- [MCP Session](https://github.com/pguso/mcp-from-scratch/blob/main/12-mcp-and-agents/src/mcp-session.js): client session · Reusable handshake, list, and call layer for agents. · `12-mcp-and-agents/src/mcp-session.js`
- [Tool Schema](https://github.com/pguso/mcp-from-scratch/blob/main/12-mcp-and-agents/src/tool-schema.js): adapter · Converts MCP tools into model-consumable tool schemas. · `12-mcp-and-agents/src/tool-schema.js`
- [LangChain Example](https://github.com/pguso/mcp-from-scratch/blob/main/12-mcp-and-agents/langchain-example/agent.mjs): integration example · Alternative agent integration using LangChain MCP adapters. · `12-mcp-and-agents/langchain-example/agent.mjs`

### Shared

Repo-level assets and root module settings.

- [ESM Root](https://github.com/pguso/mcp-from-scratch/blob/main/package.json): package setting · Root Node.js module mode for the tutorial repo. · `package.json`
- [Diagrams](https://github.com/pguso/mcp-from-scratch/tree/main/images): shared assets · Repo-wide visual assets used by the tutorial. · `images`

## Connections

- 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.
