Project

mcp-deep-dive

Protocol-first MCP reference in TypeScript — a custom server and client, all three capabilities, stdio and HTTP transports, wire-level JSON-RPC logging.

  • #ai
  • #mcp
  • #typescript
  • #open-source

mcp-deep-dive is an open-source reference implementation of the Model Context Protocol in TypeScript that I built: github.com/AleSZanello/mcp-deep-dive.

The problem

Most public MCP examples are server-only and go through LangChain adapters that hide the protocol. I wanted to see the protocol itself, so this repo implements both sides — a custom server and a custom client on the raw @modelcontextprotocol/sdk — so every JSON-RPC frame is visible: initialize, capability negotiation, tools/list, tools/call and errors.

Design

  • All three capabilities, prompts included. The server domain is a personal knowledge-notes store over a local Markdown folder, chosen because it exercises every capability without API keys:
    • Tools (actions): notes.create, notes.update, notes.delete, notes.search
    • Resources (URI-addressable reads): note://{id}, note://recent, tag://{tag}
    • Prompts (parametrized templates): summarize-note, daily-review, extract-action-items
  • Both transports. stdio for desktop hosts such as Claude Desktop, Cursor and Windsurf, and Streamable HTTP + SSE for remote and web clients. Transport is chosen at startup and kept orthogonal to business logic.
  • Wire-level logging. A shared JSON-RPC frame logger middleware; the client's trace command runs a full handshake and dumps an annotated transcript, explained line by line in the protocol walkthrough doc.
  • pnpm monorepo with three packages: shared (Zod schemas, URI parser, frame logger), server and client (a CLI with ls, call, read, prompt and trace). It also ships a Claude Desktop config and a launcher for the official MCP Inspector.

Status

Live, 2026, MIT licensed.

Related