mcp-server-template

Шаблон с чёткой позицией для создания MCP-серверов только для чтения, которые действительно удобны агентам кодинга: I/O-стыки с таймаутами, офлайн-тесты, компактные текстовые выводы, документация с минимальными привилегиями.

Начните здесь → BUILDING.md — полный процесс от идеи до опубликованного сервера (~полдня).

Что внутри: рабочий пример сервера (HTTP-инструмент pypi_project с фиксированным источником за заглушенным стыком + чистый инструмент word_stats), офлайн-набор тестов, CI-процесс, соглашения CLAUDE.md и каркас README ниже.

Сетевой пример намеренно не принимает произвольные URL. «Только для чтения» не делает загрузчик URL безопасным: неограниченные адресаты и следующие за редиректами запросы могут открыть доступ к loopback, частным сетям или сервисам метаданных облака. pypi_project формирует только запросы https://pypi.org/..., отклоняет ввод в форме URL/пути, никогда не следует редиректам, ограничивает декодированный ответ 2 MiB и применяет 15-секундный дедлайн на всю операцию.

Каркас README для вашего сервера (замените весь этот файл)

1. # mcp-<name> + однострочное ценностное предложение жирным

2. 4-строчная запись использования (Вы: … / Агент: → вызовы инструментов / Агент: ответ)

3. Таблица инструментов (инструмент → что возвращает)

4. Установка: claude mcp add <name> -e TOKEN=... -- python -m mcp_<name> + блок .mcp.json

5. Область токена / безопасность (минимальные привилегии, заявление о режиме только для чтения)

6. Заметки о дизайне (почему только чтение, почему компактный текст, почему таймауты)

7. Лицензия + контактная строка

Используйте структуру выше напрямую; замените все имена шаблона и примеры перед публикацией производного сервера.

Related MCP server: MCP Server Template

Безопасность и конфиденциальность

• Пример отправляет в PyPI только указанное имя пакета. Не помещайте секреты или приватные идентификаторы в аргументы инструментов.

• Сводки проектов PyPI — это текст, контролируемый загрузчиком, поэтому пример намеренно исключает их из вывода, видимого агенту. Относитесь ко всему внешнему тексту как к ненадёжным данным.

• Никогда не логируйте учётные данные, заголовки авторизации, сырые приватные ответы или подсказки пользователя.

• Документируйте, какой внешний сервис получает каждый аргумент. Приватные логи CI и внутренние URL чувствительны, даже если инструмент только читает их.

• Не включайте произвольную загрузку URL в производные серверы, если вы не реализуете список разрешённых адресатов и транспорт, который нельзя обойти редиректами или DNS-ребендингом.

Разработка

python -m pip install -e ".[dev]"
ruff check . && ruff format --check .
pytest
python -m build

MIT — см. LICENSE.