mcp-demo

Минималистичный Python MCP-сервер, созданный поэтапно, чтобы каждый коммит раскрывал одну концепцию. Конечный результат: Claude Code может вызывать локальные модели Ollama (gemma3:4b / 3:12b) в качестве инструмента, перенаправляя некритичные задачи с API на домашний сервер.

Что такое MCP на самом деле?

Model Context Protocol — это стандартизированный протокол JSON-RPC 2.0, который позволяет LLM-клиенту (Claude Code, Claude Desktop, Cursor) обнаруживать и вызывать инструменты, получать ресурсы и загружать шаблоны промптов из отдельных процессов, называемых MCP-серверами. 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

• Клиент — встроен в LLM-приложение

• Сервер — любой процесс, поддерживающий MCP

• Транспорт — stdio (клиент запускает сервер как дочерний процесс, передает JSON-RPC через каналы) или streamable-http (сервер как веб-сервис). В этом репозитории используется stdio.

Три примитива, предоставляемые MCP-сервером

Этапы разработки

Каждый этап — это один коммит, git log показывает эволюцию.

1. ✅ каркас — pyproject, README, .gitignore.

2. ✅ hello-world сервер — один инструмент echo + клиент для дымового тестирования. Демонстрирует полный жизненный цикл: запуск клиентом → рукопожатие → обнаружение инструмента → вызов инструмента.

3. ✅ инструмент ollama_ask — асинхронный инструмент, который отправляет POST-запрос на localhost:11434/api/generate и возвращает ответ Gemma.

4. ✅ полировка — добавляет параметр system в ollama_ask и предоставляет ресурс по адресу 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

Сервер считывает JSON-RPC из stdin и записывает в 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

• Инспектор (интерфейс отладки для тестирования любого MCP-сервера): npx @modelcontextprotocol/inspector