MCP From-Scratch Implementation

An MCP (Model Context Protocol) implementation built from scratch, primarily to learn and understand how MCP works under the hood.

The project evolves incrementally through defined phases, starting from the smallest possible working implementation and growing toward a production-grade MCP server. It is intended to serve both as a learning reference and as a real MCP server for integration testing with other AI/LLM/agent codebases.

Status: Phase 1 — Minimal MCP server. A JSON-RPC 2.0 message loop with the initialize/ping handshake over stdio. Tools, resources, and prompts arrive in later phases.

What is MCP?

MCP is an open protocol that standardizes how applications (hosts) give large language models (LLMs) access to external data and tools. It defines a client–server architecture:

User
 |
 v
LLM / Agent
 |
 v
MCP Client
 |   MCP Protocol
 v
MCP Server
 |
 +---- Tool
 |
 +---- Resource
 |
 +---- Prompt
 |
 v
External System

The three core server primitives are:

• Tools — "do something" (actions the LLM can invoke).

• Resources — "give me information/data" (data the LLM can read).

• Prompts — reusable prompt templates.

Deeper explanations of each concept are added to docs/ as the project progresses.

Related MCP server: MCP AI Chat LangChain

Project Structure

.
├── src/
│   └── mcp_server/        # The MCP server package (grows over phases)
│       ├── __init__.py    #   package exports (public API)
│       ├── protocol.py    #   JSON-RPC 2.0 messages / parsing
│       ├── server.py      #   Server: dispatch, initialize, ping
│       ├── stdio.py       #   stdio transport loop
│       └── __main__.py    #   `python -m mcp_server`
├── tests/                 # Automated tests (pytest)
├── examples/              # Runnable example applications
├── docs/                  # Concept + design documentation
├── .github/               # Repository configuration/instructions
├── .gitignore
├── README.md
├── pyproject.toml
└── uv.lock

Setup

Requirements:

• uv (Python 3.11+)

Create the virtual environment and install dependencies (including dev dependencies) from the project root:

uv sync

This creates .venv/ and installs the project in editable mode plus pytest.

Running the Server

The server speaks JSON-RPC 2.0 over stdio: each message is one JSON object per line on standard input, with responses written to standard output.

uv run mcp-server

or equivalently:

uv run python -m mcp_server

For example, sending an initialize request and a ping:

$ printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' \
  '{"jsonrpc":"2.0","id":2,"method":"ping"}' | uv run mcp-server
{"jsonrpc": "2.0", "id": 1, "result": {"protocolVersion": "2025-06-18", "capabilities": {}, "serverInfo": {"name": "mcp-server", "version": "0.2.0"}}}
{"jsonrpc": "2.0", "id": 2, "result": {}}

Running the Tests

uv run pytest

Development Roadmap

The project is developed in phases (see .github/copilot-instructions.md for full details):

Coding Guidelines

• Modern Python with type hints.

• Small functions, clear naming, explicit error handling.

• Interfaces/abstractions only when justified.

• pytest for testing.

• Dependencies are added only with justification.

License

(Not yet specified.)