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 0 — Project Foundation. No MCP functionality is implemented yet.

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
│       └── server.py
├── 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 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.)