nanomcp

Это минималистичный демо-пример MCP, написанный вручную без использования MCP Python SDK. Он содержит полный цикл:

1. nanomcp.server в качестве MCP-сервера, отправляющего и принимающего JSON-RPC через stdio.

2. nanomcp.cli в качестве MCP-клиента/хоста, который запускает сервер и выполняет initialize, tools/list и tools/call.

3. Команда chat вызывает OpenAI Chat Completions. После того как модель возвращает вызов функции/инструмента (function/tool call), CLI преобразует его в MCP tools/call, а затем отправляет результат работы инструмента обратно модели для генерации итогового ответа.

Связь между MCP и function call

В двух словах: function call — это возможность API модели, при которой «модель сообщает вашему приложению, какую функцию она хочет вызвать»; MCP — это протокол соединения, который определяет, «как ваше приложение использует единый протокол для обнаружения и вызова внешних инструментов или сервисов контекста».

Более конкретно:

• Function/tool calling происходит между LLM API <-> вашим приложением. Модель не выполняет функцию на самом деле, она лишь возвращает намерение вызова, например {"name":"get_weather","arguments":{...}}.

• MCP происходит между вашим приложением <-> MCP-сервером. MCP-сервер предоставляет список инструментов и точку входа для их выполнения, например tools/list и tools/call.

• Хост/клиент выступает посредником. Сначала он получает схему инструментов от MCP-сервера и преобразует эти схемы в инструменты API модели; после того как модель выбирает инструмент, хост/клиент вызывает MCP-сервер.

Цепочка в данном проекте выглядит так:

用户问题
  -> nanomcp.cli
  -> OpenAI Chat Completions tools=function schemas
  <- 模型返回 tool_calls
  -> nanomcp.cli 把 tool_call 映射为 MCP tools/call
  -> nanomcp.server 执行 get_weather 或 find_files
  <- MCP tool result
  -> nanomcp.cli 把结果发回模型
  <- 模型最终回答

Поэтому они находятся на разных уровнях:

Function call: 模型 API 的工具选择/参数生成机制
MCP: 应用连接工具服务器的标准协议

Related MCP server: MCP Server Demo

Структура файлов

nanomcp/
  nanomcp/
    cli.py       # MCP client + model caller
    server.py    # hand-written MCP server over stdio
  tests/
    test_protocol.py
  pyproject.toml
  README.md

Запуск MCP напрямую, без вызова модели

Запустите в директории проекта:

cd ~/Desktop/nanomcp
python3 -m nanomcp.cli list-tools

Прямой вызов инструмента погоды:

python3 -m nanomcp.cli call get_weather '{"location":"Shanghai","unit":"celsius"}'

Прямой вызов инструмента текущей даты и времени:

python3 -m nanomcp.cli call get_current_datetime '{"timezone":"Asia/Shanghai"}'

Прямой вызов инструмента поиска файлов:

python3 -m nanomcp.cli call find_files '{"query":"*.pdf","max_results":5}'

По умолчанию поиск ведется только в ~/Desktop. Вы можете временно расширить или сузить корневую директорию поиска:

NANOMCP_FILE_ROOT=~/Desktop/nanomcp python3 -m nanomcp.cli call find_files '{"query":"*.py"}'

Запуск полной цепочки модель + MCP

Требуется API-ключ OpenAI. Здесь не используется OpenAI Python SDK, вместо этого для отправки HTTP-запросов используется стандартная библиотека urllib.

Рекомендуется записать локальную конфигурацию в .env:

cd ~/Desktop/nanomcp
cp .envtemplate .env

Затем отредактируйте .env:

OPENAI_API_KEY=你的 key
OPENAI_BASE_URL=https://api.openai.com/v1
NANOMCP_MODEL=gpt-4.1-mini
NANOMCP_TIMEZONE=Asia/Shanghai

Файл .env автоматически считывается CLI и уже добавлен в .gitignore.

cd ~/Desktop/nanomcp
python3 -m nanomcp.cli chat "上海今天天气怎么样？顺便帮我找桌面上的 PDF 文件"

Модель по умолчанию — gpt-4.1-mini. Вы можете изменить её:

NANOMCP_MODEL=gpt-5-mini python3 -m nanomcp.cli chat "找一下这个项目里的 py 文件"

Если вы используете шлюз, совместимый с OpenAI:

OPENAI_BASE_URL=http://localhost:8000/v1 python3 -m nanomcp.cli chat "上海天气怎么样？"

Легкая проверка локальной конфигурации и MCP-сервера:

python3 -m nanomcp.cli doctor

Устранение неполадок

Если chat выводит OpenAI API quota is exhausted (429 insufficient_quota), это означает, что API модели отклонило запрос: у проекта, к которому относится OPENAI_API_KEY, нет доступных квот или не настроен биллинг. Это не ошибка MCP-сервера, так как запрос был отклонен еще до того, как модель вернула вызов инструмента.

Порядок проверки:

python3 -m nanomcp.cli doctor
echo "$OPENAI_API_KEY"
cat .env
python3 -m nanomcp.cli call get_weather '{"location":"Shanghai"}'
OPENAI_BASE_URL=http://localhost:8000/v1 python3 -m nanomcp.cli chat "上海天气怎么样？"

• Первая команда отображает (без чувствительных данных) эффективную конфигурацию, проверяет, переопределяет ли shell файл .env, и может ли MCP-сервер перечислить инструменты.

• Вторая команда подтверждает, установлен ли ключ в shell.

• Третья команда подтверждает локальную конфигурацию в .env.

• Четвертая команда проверяет, работает ли локальная цепочка MCP без зависимости от API модели.

• Пятая команда демонстрирует, как переключиться на шлюз, совместимый с OpenAI.

• Если вы по-прежнему используете официальный API OpenAI, вам нужно сменить ключ/проект, у которого есть квоты, или проверить биллинг и права доступа к модели.

Опциональная реальная погода

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

NANOMCP_LIVE_WEATHER=1 python3 -m nanomcp.cli call get_weather '{"location":"Shanghai"}'

Реальная погода использует https://wttr.in, при сбое автоматически происходит откат к демо-данным.

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

cd ~/Desktop/nanomcp
python3 -m unittest discover -s tests

Тестирование охватывает:

• MCP initialize

• MCP tools/list

• MCP tools/call get_weather

• MCP tools/call find_files

• MCP tools/call get_current_datetime

Ключевые наблюдения

Посмотрите на openai_tools_from_mcp() в nanomcp/cli.py: она преобразует схему инструментов MCP в схему инструментов функций OpenAI.

Посмотрите на run_chat(): после получения tool_calls от модели она вызывает mcp.call_tool(). Это и есть точка сопряжения MCP и function call.

Посмотрите на main() в nanomcp/server.py: он только читает stdin и пишет в stdout, каждая строка — это JSON-RPC. Сервер ничего не знает об OpenAI и не взаимодействует с моделью напрямую.