MCP-сервер и клиент

PersonalKB: настоящий сервер Model Context Protocol (MCP), поиск по заметкам плюс получение актуальной погоды, а также клиент/агент, который с ним общается. Слой протокола MCP никогда не мокируется: каждый тест запускает реальный дочерний процесс сервера и выполняет через него настоящий JSON-RPC — либо через stdio, либо через настоящий HTTP. Единственное, что имитируется офлайн, — это собственное решение LLM о выборе инструмента; для запуска чего-либо здесь не нужен API-ключ, кроме финального флага --real.

Проблема: Подключение модели к инструментам с помощью собранного вручную JSON-блоба работает, пока вам не понадобится второй клиент, удалённый сервер или чужие инструменты. Вместо этого MCP — открытый стандарт Anthropic, описывающий, как модель обнаруживает и вызывает инструменты, читает ресурсы и использует шаблоны промптов через реальный сетевой протокол. Этот проект создаёт настоящий сервер по этому протоколу — от декораторов до работающего клиентского моста и агентского цикла.

Продемонстрированные навыки: создание MCP-сервера (инструменты, ресурсы, промпты) с помощью FastMCP, транспорты stdio и streamable-HTTP, клиентский мост, который обнаруживает инструменты вживую через протокол, детерминированный офлайн-маршрутизатор инструментов и настоящий агентский цикл через Claude API, полнотекстовый поиск SQLite (FTS5) и pytest на реальном протокольном трафике (без моков).

Технологический стек: Python 3.10+, SDK mcp (FastMCP), SQLite (стандартная библиотека), Anthropic SDK для реального агентского пути, requests для получения актуальной погоды (Open-Meteo), pytest.

Что предоставляет сервер

Запуск mcp_kb.server поднимает MCP-сервер PersonalKB, работающий с заметками, хранящимися в SQLite с полнотекстовым поиском:

• Инструменты: search_notes(query, limit), add_note(title, body, tags), list_tags(), get_weather(city).

• Ресурсы: note://{note_id} (получить одну заметку), notebook://summary (сводка по всей записной книжке).

• Промпт: research_prompt(topic) — переиспользуемый шаблон промпта.

Related MCP server: MCP Apple Notes

Запуск

python -m venv .venv ; .\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
python generate_data.py           # seeds data/notes.db with 15 hand-written notes

python -m mcp_kb tools                                  # list tools/resources/prompts
python -m mcp_kb ask "find notes about python"
python -m mcp_kb ask "what's the weather in Paris"
python -m mcp_kb serve                                  # run the server directly (stdio)
python -m mcp_kb serve --http                            # or over streamable-HTTP

pytest -q                          # the full suite, all real protocol traffic, no key needed

ask запускает настоящий сервер, обнаруживает его инструменты вживую через MCP и отвечает на ваш вопрос по умолчанию с помощью детерминированного офлайн-маршрутизатора, либо через настоящий Claude API с флагом --real (требуется ANTHROPIC_API_KEY в .env).

Как это устроено

mcp_kb/
├── db.py         SQLite + FTS5 notes store: search, add, tags
├── weather.py     an offline table, or real keyless Open-Meteo data with --live-weather
├── server.py      the actual MCP server (FastMCP-based): tools, resources, a prompt
├── bridge.py       the MCP client wrapper: discovers tools/resources/prompts live
├── llm.py         the offline deterministic tool-choice router
├── agent.py        the agentic loop: offline router, or a real Claude tool-use loop
└── cli.py           python -m mcp_kb tools|ask|serve
tests/                41 tests, all real protocol traffic (stdio and HTTP), no mocking

Ключевое архитектурное решение: server.py — тонкая обёртка вокруг db.py и weather.py; единственная задача слоя MCP — перевод между протоколом и обычными Python-функциями. Именно это разделение делает базовую логику