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: mcp-anvil-lite

구현된 것

범위는 의도적입니다: 리소스, 프롬프트, 샘플링, 알림은 제외합니다. 도구 하위 집합은 에이전트가 의존하는 부분이며, 완전한 작은 것이 불완전한 큰 것보다 낫습니다.

논쟁할 만한 설계 결정

전송-독립적 서버. handle_line은 하나의 요청 문자열을 하나의 응답 문자열로 매핑합니다. 같은 서버가 stdio, 소켓, 또는 직접 호출하는 단위 테스트에서도 동작합니다 — 그래서 프로토콜 테스트는 서브프로세스가 필요 없고 절대 실패하지 않습니다.

알 수 없는 도구 인자는 무시되지 않고 거부됩니다. 선언하지 않은 매개변수를 받는 도구는 프로덕션으로 가는 버그입니다. 여기서의 엄격함이 에이전트 도구 호출을 디버깅 가능하게 만듭니다.

도구 예외는 크래시가 아니라 프로토콜 오류가 됩니다. 버그가 있는 도구가 서버나 세션을 죽여서는 안 됩니다. 클라이언트는 메시지와 함께 -32603을 받고, 루프는 계속됩니다.

bool은 integer가 아닙니다. Python의 bool은 int의 하위 클래스이므로, 단순한 검증기는 True를 개수가 필요한 곳에 허용합니다. 이 구현은 그렇지 않으며, 테스트가 이를 고정합니다.

테스트

PYTHONPATH=src python3 -m pytest tests -q

핸드셰이크, 발견, 유효한 호출과 유효하지 않은 호출, 모든 JSON-RPC 오류 코드를 다루며, 실제 클라이언트를 실제 서버에 서브프로세스로 실행하는 엔드투엔드 테스트 하나가 포함됩니다.

라이선스

MIT