mcp-trial

Я изучаю Model Context Protocol, создавая сервер для GitHub API. Python SDK v2, работает через stdio и подключён к Claude Code.

Что он делает

Два инструмента: один для сводки по репозиторию, другой для недавних сообщений коммитов. Также есть ресурс, который отдаёт сырой README репозитория, и шаблон промпта для оценки репозитория как элемента портфолио.

Related MCP server: MCP GitHub Reader

Запуск

uv sync
uv run mcp dev server.py          # opens the inspector
uv run python test_server.py      # calls the server directly, no host needed

Чтобы зарегистрировать его в Claude Code:

claude mcp add gh-lab -- uv run --directory /path/to/mcp-trial mcp run server.py

Что я узнал

Ваши аннотации типов — это фактический контракт API, поскольку SDK строит JSON-схему инструмента прямо из сигнатуры функции. Написание limit: int = 5 также делает этот параметр необязательным, так что модель может его пропустить.

Docstrings оказались важнее, чем я ожидал, потому что они отправляются модели как описание инструмента и определяют, какой инструмент она выберет. Я спросил Claude Code, активно ли поддерживается репозиторий, и он вызвал оба инструмента и разобрался, что произошло только потому, что описания делали их совместимыми.

Всё, что возвращает инструмент, становится текстом в контексте модели, поэтому каждое поле стоит токенов. GitHub отдаёт около сотни полей, а я возвращаю пять.

Выбрасывание ошибки лучше, чем возврат, поскольку выбрасывание устанавливает флаг, который проверяет хост, и сообщение доходит до модели как то, на что она может отреагировать.

Async ничего не ускоряет. Один вызов занимает одинаковое время в любом случае. Что делает await — это приостанавливает функцию и освобождает цикл событий, чтобы другие вызовы могли выполняться во время ожидания.

Заметки

mcp-reference.md содержит мои рабочие заметки по созданию этого.