Skip to main content
Glama
mcp-lab-00-raw-protocol

mcp-lab-00-raw-protocol

by lucas-moont

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.

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.

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)

Related MCP server: node-mcp-poc

Como rodar

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:

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/ explicando o pra-quê, o quê e como:

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

Available Tools

1 tool
addA

Soma dois números e devolve o resultado.

Inputs: a (required), b (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.8/5.0

    Scored across 1 tool

    Disambiguation5/5

    Only one tool exists, so there is no possibility of overlapping or ambiguous tool purposes. The single 'add' tool has a clear, singular function.

    Naming Consistency4/5

    The tool name 'add' is clear, concise, and uses a lowercase verb style. With only one tool, there is no established pattern to fully evaluate, but the naming is appropriate and unambiguous.

    Tool Count3/5

    A single tool feels minimal and thin for most practical use cases. It is not necessarily inappropriate for a very narrow addition-only server, but the count is at the borderline lower end.

    Completeness2/5

    The tool set only supports addition. If the intended domain is basic arithmetic, significant operations such as subtraction, multiplication, and division are missing, leaving substantial gaps.

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      B
      quality
      Not graded
      maintenance
      A minimal Model Context Protocol server that provides a simple tool for adding two integers. It serves as a demonstration of the official Python MCP SDK and is designed for local execution via stdio.
      1
      -
    • F
      license
      Not graded
      quality
      D
      maintenance
      A minimal MCP server that exposes tools for addition, echoing text, time lookup, and URL fetching, with support for HTTP and stdio transports.
      -
    • F
      license
      Not graded
      quality
      D
      maintenance
      A model-agnostic MCP server exposing example tools (add1, multiply2, greet) for learning purposes, working with any LLM through stdio transport.
      -
    • F
      license
      A
      quality
      D
      maintenance
      A learning-oriented MCP server that exposes basic tools (echo, add, reverse) over stdio transport to validate MCP handshake and tool calls.
      3
      -