mini-mcp

MCP (Model Context Protocol), implementado desde primeros principios en ~200 líneas legibles. Un servidor, un cliente y la mecánica JSON-RPC entre ellos: el núcleo de llamada a herramientas del que depende toda integración de agentes, lo suficientemente pequeño como para leerse de una sentada.

git clone https://github.com/harshadkhetpal/mini-mcp
cd mini-mcp
PYTHONPATH=src python3 -m minimcp.client

connected: mini-mcp-demo protocol 2025-06-18
tools discovered: calc.add, text.word_count, text.summarize_naive
calc.add(2, 40) -> 42
word_count -> 6

Por qué construir esto cuando existen SDKs

Los frameworks ocultan el protocolo, y los protocolos ocultos producen ingenieros que pueden cablear una integración pero no depurarla. Implementar el núcleo enseña lo que realmente hacen los SDKs: MCP es JSON-RPC 2.0 sobre un transporte, más tres métodos que importan: initialize (handshake y capacidades), tools/list (descubrimiento con descripciones JSON-Schema) y tools/call (invocación validada). Una vez entendido esto, cada SDK de MCP se lee como un envoltorio de conveniencia, que es lo que es.

Related MCP server: toolbox-mcp

Qué está implementado

El alcance es deliberado: recursos, prompts, muestreo y notificaciones quedan fuera. El subconjunto de herramientas es la parte en la que viven los agentes, y una cosa pequeña y completa supera a una grande e incompleta.

Decisiones de diseño que merecen discusión

Servidor independiente del transporte. handle_line mapea una cadena de solicitud a una cadena de respuesta. El mismo servidor funciona sobre stdio, un socket o una prueba unitaria que lo llama directamente — por eso las pruebas del protocolo no necesitan subprocesos y nunca fallan.

Los argumentos desconocidos de las herramientas se rechazan, no se ignoran. Una herramienta que recibe parámetros que nunca declaró es un bug en camino a producción. La estrictez aquí es lo que hace depurable la llamada a herramientas de los agentes.

Las excepciones de las herramientas se convierten en errores de protocolo, no en caídas. Una herramienta con errores no debe tumbar el servidor ni la sesión; el cliente recibe -32603 con el mensaje, y el bucle continúa.

bool no es un integer. El bool de Python subclasifica int, por lo que los validadores ingenuos aceptan True donde corresponde un recuento. Este no lo hace, y una prueba lo fija.

Pruebas

PYTHONPATH=src python3 -m pytest tests -q

Cubren el handshake, el descubrimiento, llamadas válidas e inválidas, cada código de error JSON-RPC, y una prueba de extremo a extremo que ejecuta el cliente real contra el servidor real como subproceso.

Licencia

MIT