mcp-demo

각 커밋을 통해 개념을 하나씩 학습할 수 있도록 단계별로 구축된 최소한의 Python MCP 서버입니다. 최종 상태: Claude Code가 로컬 Ollama 모델(gemma3:4b / 3:12b)을 도구로 호출하여, 중요도가 낮은 작업을 API에서 홈랩으로 전환합니다.

MCP란 무엇인가?

**Model Context Protocol(모델 컨텍스트 프로토콜)**은 LLM 클라이언트(Claude Code, Claude Desktop, Cursor)가 MCP 서버라고 불리는 별도의 프로세스에서 도구를 검색 및 호출하고, 리소스를 가져오며, 프롬프트 템플릿을 로드할 수 있게 해주는 표준화된 JSON-RPC 2.0 프로토콜입니다. MCP와 LLM 도구의 관계는 LSP와 IDE 언어 지원의 관계와 같습니다. 즉, 하나의 프로토콜로 여러 상호 운용 가능한 구현을 지원합니다.

구성 요소

    ┌───────────────────┐  stdio / HTTP   ┌──────────────────┐
    │  MCP Client       │ ◄──JSON-RPC──► │  MCP Server      │
    │  (Claude Code)    │                │  (this repo)     │
    └───────────────────┘                └──────────────────┘
            │                                     │
            │ spawns as child                     │ hits
            │ process (stdio)                     │ localhost:11434
            ▼                                     ▼
     your shell env                        Ollama / gemma3

• 클라이언트(Client) — LLM 앱에 내장됨

• 서버(Server) — MCP를 지원하는 모든 프로세스

• 전송(Transport) — stdio(클라이언트가 서버를 자식 프로세스로 생성하고 JSON-RPC를 파이프로 연결) 또는 streamable-http(서버가 웹 서비스로 작동). 이 저장소는 stdio를 사용합니다.

MCP 서버가 노출하는 세 가지 기본 요소

단계별 진행

각 단계는 하나의 커밋으로 구성되어 있으며, git log를 통해 발전 과정을 확인할 수 있습니다.

1. ✅ 스캐폴드(scaffold) — pyproject, README, .gitignore 설정.

2. ✅ hello-world 서버 — 하나의 echo 도구 + 스모크 테스트 클라이언트. 전체 수명 주기(클라이언트 생성 → 핸드셰이크 → 도구 검색 → 도구 호출)를 증명합니다.

3. ✅ ollama_ask 도구 — localhost:11434/api/generate에 POST 요청을 보내고 Gemma의 응답을 반환하는 비동기 도구.

4. ✅ 다듬기(polish) — ollama_ask에 system 매개변수를 추가하고 ollama://models(다운로드된 모델 목록) 리소스를 노출합니다.

설치 및 실행

python3 -m venv .venv
source .venv/bin/activate
pip install -e .
# Phase 2+ only: run the server by hand to smoke-test
python -m mcp_demo.server

서버는 stdin에서 JSON-RPC를 읽고 stdout으로 씁니다. 터미널에서 직접 실행하면 입력 대기 상태로 멈춰 있는 것처럼 보입니다. 이는 정상입니다. 클라이언트(Claude Code)가 실제로 데이터를 공급합니다.

Claude Code에 등록하기

~/.claude/settings.json에 다음을 추가하세요:

{
  "mcpServers": {
    "mcp-demo": {
      "command": "/home/booty/mcp-demo/.venv/bin/python",
      "args": ["-m", "mcp_demo.server"]
    }
  }
}

Claude Code를 재시작하세요. 도구는 mcp__mcp-demo__<tool_name>으로 나타납니다.

추가 읽기 자료

• 사양: https://modelcontextprotocol.io/specification

• Python SDK: https://github.com/modelcontextprotocol/python-sdk

• Inspector (모든 MCP 서버를 디버깅하기 위한 UI): npx @modelcontextprotocol/inspector