# mcp-lab-00-raw-protocol

Nível 00 da trilha **MCP Lab**: implementação **manual** do protocolo MCP (Model Context Protocol) sobre stdio, sem usar o SDK oficial. O objetivo não é construir um servidor útil — é ver as mensagens JSON-RPC trocando de lado a lado com as próprias mãos, antes de deixar um SDK esconder isso de você.

Termos técnicos (Tool, Server, Client, Transport...) seguem o glossário em [`../CONTEXT.md`](../CONTEXT.md).

## O que este Server faz

Um único Tool, de propósito — `add`, que soma dois números. É só o suficiente pra passar pelo ciclo completo: handshake → listar Tools → chamar um Tool.

```mermaid
sequenceDiagram
    participant H as Host (Claude Code)
    participant S as Server (este projeto)

    H->>S: initialize (id: 1, protocolVersion)
    S-->>H: result (protocolVersion, capabilities, serverInfo)
    H->>S: notifications/initialized
    Note over S: sem resposta — é uma Notification
    H->>S: tools/list (id: 2)
    S-->>H: result (lista de Tools: "add")
    H->>S: tools/call (id: 3, name: "add", arguments: {a, b})
    S-->>H: result (content: texto com a soma)
```

## Como rodar

```bash
uv sync                 # instala as dependências
uv run pytest -q        # roda os 15 testes
uv run ruff check .     # lint
uv run mypy             # checagem de tipos (modo strict)
```

Pra ver o protocolo funcionando de verdade, sem o SDK, sem o Claude Code — só você mandando as mensagens na mão:

```bash
printf '%s\n' \
  '{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2025-06-18"}}' \
  '{"jsonrpc": "2.0", "method": "notifications/initialized"}' \
  '{"jsonrpc": "2.0", "id": 2, "method": "tools/list"}' \
  '{"jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": {"name": "add", "arguments": {"a": 4, "b": 5}}}' \
  | uv run raw-mcp-protocol
```

## Estrutura do código

```
src/raw_mcp_protocol/
├── jsonrpc.py   → camada de transporte: lê/escreve linhas JSON, não entende o conteúdo
├── server.py    → camada de lógica: decide a resposta pra cada "method"
└── __init__.py  → ponto de entrada: liga as duas camadas num loop
```

Cada camada tem seu próprio `.md` em [`docs/`](./docs/) explicando o pra-quê, o quê e como:

- [`docs/01-transporte-stdio.md`](./docs/01-transporte-stdio.md)
- [`docs/02-jsonrpc.md`](./docs/02-jsonrpc.md)
- [`docs/03-handshake-initialize.md`](./docs/03-handshake-initialize.md)
- [`docs/04-tools.md`](./docs/04-tools.md)

## O que este nível deliberadamente NÃO faz

- Não valida rigorosamente o ciclo de vida (chamar `tools/call` antes do `initialize` não é bloqueado) — fica como leitura, não como bloqueio ativo.
- Não implementa Resources, Prompts, Sampling, Roots nem Elicitation — isso é o Nível `02-resources-prompts` em diante.
- Não roda sobre HTTP — isso é o Nível `04-remote-http-auth`.

## Referência oficial

[modelcontextprotocol.io/specification](https://modelcontextprotocol.io/specification) — a fonte da verdade. As versões de protocolo hardcoded em `server.py` (`SUPPORTED_PROTOCOL_VERSIONS`) devem ser conferidas contra essa página se você estiver lendo isto muito tempo depois de escrito.