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

---

## 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](https://docs.astral.sh/uv/) (Python 3.11+)

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

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

```bash
uv run mcp-server
```

or equivalently:

```bash
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

```bash
uv run pytest
```

---

## Development Roadmap

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

| Phase | Focus                            |
| ----- | -------------------------------- |
| 0     | Project foundation (this phase)  |
| 1     | Minimal MCP server               |
| 2     | Tools                            |
| 3     | Resources                        |
| 4     | Prompts                          |
| 5     | MCP client                       |
| 6     | LLM / agent integration          |
| 7     | Error handling and validation    |
| 8     | Logging and observability        |
| 9     | Configuration and secrets        |
| 10    | Authentication and authorization |
| 11    | Testing                          |
| 12    | Transport and deployment         |
| 13    | Security hardening               |
| 14    | Production-grade MCP server      |

---

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