pguso/mcp-from-scratch

★ 15JavaScriptAudience · developerComplexity · 2/5Setup · easy

Mindmap

mindmap
  root((MCP from scratch))
    What it is
      MCP learning course
      12 numbered modules
      Zero dependencies
    Protocol concepts
      JSON-RPC messages
      Stdio transport
      Tool registration
      Resource exposure
    End result
      Working MCP server
      Claude Desktop connection
    Requirements
      Node.js 20 or later
      Basic JavaScript

mindmap root((MCP from scratch)) What it is MCP learning course 12 numbered modules Zero dependencies Protocol concepts JSON-RPC messages Stdio transport Tool registration Resource exposure End result Working MCP server Claude Desktop connection Requirements Node.js 20 or later Basic JavaScript

Click or tap to explore — scroll the page freely

Things people build with this

USE CASE 1

Learn exactly how MCP works under the hood by building a server step-by-step with no abstraction libraries.

USE CASE 2

Create a working MCP server that Claude Desktop can connect to, following the 12-module progression.

USE CASE 3

Understand JSON-RPC message structure and stdio transport to debug or extend existing MCP integrations.

Tech stack

JavaScriptNode.js

Getting it running

Difficulty · easy Time to first run · 30min

Modules 11-12 require downloading roughly 1.5 GB of local model files via node-llama-cpp.

In plain English

This is a step-by-step learning repository for understanding the Model Context Protocol, often called MCP. MCP is a communication standard that lets AI tools like Claude talk to external programs, databases, or other services. The project teaches that standard from first principles, in plain Node.js with no extra libraries or abstraction layers, so you can see exactly what is happening at each step. The course is organized into 12 numbered modules, each focused on one narrow question. Module one explains what MCP is and why it exists. Module two covers JSON-RPC, the message format the protocol uses. From there each module adds one layer: how messages travel over standard input and output, how a server and client establish a connection, how tools get registered and called, how errors are reported, how resources are exposed, how prompts work, and finally how an MCP server fits into a broader agent workflow. By the time you finish module 12, you have a working server you can connect to Claude Desktop. The directory structure follows a consistent pattern across modules. Each folder contains a README that opens with the question being answered, a src folder with commented source code, and a run file that shows the exact commands to type and what you should see. Modules one and six have slightly different layouts, but the README for each module explains what is different and why. One firm rule applies to the first ten modules: no npm packages. Every server in those modules runs with a single node command and zero dependencies. This is intentional. The goal is to make every line of the protocol visible. Modules eleven and twelve break that rule only for local language model support, which requires a library called node-llama-cpp and downloads roughly 1.5 gigabytes of model files on first use. You need Node.js version 20 or later and the ability to read basic JavaScript. Prior knowledge of networking, protocols, or AI systems is not required. The only entry point is cloning the repository and opening the README in module one.

Copy-paste prompts

Prompt 1

I am working through mcp-from-scratch module 4. Explain what happens during the MCP handshake when a client and server establish a connection, and show me the exact JSON-RPC messages exchanged.

Prompt 2

Using the patterns from mcp-from-scratch, write a minimal Node.js MCP server that exposes a single tool called get_weather that accepts a city name and returns a fake weather response.

Prompt 3

I finished module 12 of mcp-from-scratch and have a working server. Help me register it in Claude Desktop config so it shows up as an available tool.

Prompt 4

Explain the difference between tools, resources, and prompts in MCP and show me a minimal implementation of each based on the mcp-from-scratch module structure.

Open on GitHub → Explain another repo

← pguso on gitmyhub — every repo by this author, as a profile.

Verify against the repo before relying on details.