mini-mcp

MCP (Model Context Protocol), реализованный с нуля примерно в ~200 читаемых строк. Сервер, клиент и JSON-RPC-механика между ними — ядро вызова инструментов, от которого зависят все интеграции агентов, достаточно маленькое, чтобы прочитать его за один присест.

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

Зачем это делать, когда существуют SDK

Фреймворки скрывают протокол, а скрытые протоколы порождают инженеров, которые могут подключить интеграцию, но не могут её отладить. Реализация ядра показывает, что на самом деле делают SDK: MCP — это JSON-RPC 2.0 поверх транспорта плюс три метода, которые имеют значение — initialize (рукопожатие и возможности), tools/list (обнаружение с JSON-Schema описаниями) и tools/call (валидированный вызов). Как только это понято, любой MCP SDK читается как удобная обёртка, чем он и является.

Related MCP server: toolbox-mcp

Что реализовано

Область применения осознанная: ресурсы, промпты, сэмплирование и уведомления исключены. Подмножество инструментов — это та часть, на которой живут агенты, и полная маленькая вещь лучше неполной большой.

Проектные решения, с которыми стоит поспорить

Транспортно-независимый сервер. handle_line отображает одну строку запроса в одну строку ответа. Один и тот же сервер работает через stdio, сокет или юнит-тест, вызывающий его напрямую — именно поэтому протокольные тесты не требуют подпроцессов и никогда не флакают.

Неизвестные аргументы инструмента отклоняются, а не игнорируются. Инструмент, получающий параметры, которые он никогда не объявлял, — это баг на пути в продакшн. Строгость здесь — это то, что делает отладку вызовов инструментов агента возможной.

Исключения инструментов становятся протокольными ошибками, а не падениями. Баговый инструмент не должен ронять сервер или сессию; клиент получает -32603 с сообщением, и цикл продолжается.

bool — это не integer. В Python bool является подклассом int, поэтому наивные валидаторы принимают True там, где ожидается счётчик. Этот — нет, и тест это закрепляет.

Тестирование

PYTHONPATH=src python3 -m pytest tests -q

Покрывает рукопожатие, обнаружение, валидные и невалидные вызовы, каждый код ошибки JSON-RPC и один сквозной тест, запускающий реальный клиент против реального сервера как подпроцесс.

Лицензия

MIT