Шаблон MCP-сервера

Минималистичная, хорошо документированная реализация MCP-сервера (Model Context Protocol), разработанная в качестве базовой основы для создания пользовательских MCP-серверов.

Что такое MCP?

Model Context Protocol (MCP) — это стандартизированный протокол, позволяющий ИИ-ассистентам взаимодействовать с внешними серверами. MCP-серверы могут предоставлять:

• Инструменты (Tools): функции, которые ИИ может вызывать для выполнения действий

• Ресурсы (Resources): статические или динамические данные, которые ИИ может считывать

• Промпты (Prompts): повторно используемые шаблоны промптов для согласованного взаимодействия с ИИ

Related MCP server: MCP Mingdao

Возможности

Этот шаблон предоставляет:

• Минималистичную структуру: чистую базу, которую легко расширять

• Обширную документацию: встроенные комментарии и отдельные файлы документации

• Архитектурные диаграммы: диаграммы Mermaid, показывающие взаимодействие компонентов

• Руководство по масштабированию: лучшие практики для развития вашего сервера

• Подсказки типов: полные аннотации типов для лучшей поддержки IDE

• Async/await: неблокирующий ввод-вывод для параллельных операций

Повторно используемые шаблоны промптов

Промпты — это шаблоны, позволяющие определять структурированные запросы с заполнителями. Они обеспечивают:

• Согласованность: стандартизированные форматы промптов при различных взаимодействиях с ИИ

• Параметризацию: вставку динамического контента через аргументы

• Повторное использование: определите один раз, используйте многократно с разными входными данными

• Безопасность типов: определенные схемы аргументов с валидацией

Шаблон промпта состоит из:

• Имени: уникального идентификатора промпта

• Описания: того, что делает промпт

• Аргументов: необязательных параметров, которые можно заполнить при использовании промпта

Примеры использования:

• Шаблоны для проверки кода с настраиваемыми уровнями критичности

• Генерация документации с настраиваемым тоном

• Промпты для анализа с переменными областями фокусировки

• Генерация отчетов с различными форматами вывода

Структура проекта

windsurf-project-3/
├── mcp_server.py          # Main server implementation with extensive comments
├── pyproject.toml         # Project configuration for uv
├── ARCHITECTURE.md        # Architecture documentation with Mermaid diagrams
├── SCALING_GUIDE.md       # Scaling patterns and best practices
├── README.md              # This file
├── tools/                 # Placeholder for tool modules (create as needed)
├── resources/             # Placeholder for resource modules (create as needed)
├── prompts/               # Placeholder for prompt modules (create as needed)
└── utils/                 # Placeholder for utility modules (create as needed)

Установка

Этот проект использует uv для быстрого управления пакетами Python.

1. Установите Python 3.10 или выше

2. Установите uv (если еще не установлен):

curl -LsSf https://astral.sh/uv/install.sh | sh

3. Установите зависимости:

uv sync

Быстрый старт

1. Добавьте свой первый инструмент

Отредактируйте mcp_server.py и добавьте инструмент в функцию list_tools():

@app.list_tools()
async def list_tools() -> list[Tool]:
    return [
        Tool(
            name="echo",
            description="Echo back the input text",
            inputSchema={
                "type": "object",
                "properties": {
                    "text": {"type": "string", "description": "Text to echo"}
                },
                "required": ["text"]
            }
        )
    ]

2. Реализуйте обработчик инструмента

Добавьте логику инструмента в функцию call_tool():

@app.call_tool()
async def call_tool(name: str, arguments: Any) -> str:
    if name == "echo":
        text = arguments.get("text", "")
        return f"Echo: {text}"
    raise ValueError(f"Unknown tool: {name}")

3. Добавьте промпт (опционально)

Добавьте промпт в функцию list_prompts():

@app.list_prompts()
async def list_prompts() -> list[Prompt]:
    return [
        Prompt(
            name="example_prompt",
            description="An example prompt template",
            arguments=[
                PromptArgument(
                    name="topic",
                    description="The topic to write about",
                    required=True
                )
            ]
        )
    ]

Затем реализуйте обработчик в get_prompt():

@app.get_prompt()
async def get_prompt(name: str, arguments: dict[str, str] | None) -> str:
    if name == "example_prompt":
        topic = arguments.get("topic") if arguments else None
        if not topic:
            raise ValueError("Argument 'topic' is required")
        return f"Write a detailed explanation about {topic}."
    raise ValueError(f"Unknown prompt: {name}")

3. Запустите сервер

uv run python mcp_server.py

4. Настройте ваш MCP-клиент

Добавьте это в конфигурацию вашего MCP-клиента:

{
  "mcpServers": {
    "your-server-name": {
      "command": "uv",
      "args": ["run", "python", "/path/to/mcp_server.py"]
    }
  }
}

Документация

• ARCHITECTURE.md: подробная архитектурная документация с диаграммами Mermaid, показывающими:

  • Модули Python и их назначение

  • Взаимодействие компонентов

  • Потоки запросов (вызов инструментов, чтение ресурсов)

  • Используемые паттерны проектирования

• SCALING_GUIDE.md: лучшие практики масштабирования вашего сервера:

  • Паттерны модульности

  • Стратегии управления состоянием

  • Паттерны обработки ошибок

  • Логирование и мониторинг

  • Управление конфигурацией

  • Стратегии тестирования

  • Оптимизация производительности

  • Вопросы безопасности

Структура кода

Основной файл сервера (mcp_server.py) организован по разделам:

1. Инициализация сервера: создание экземпляра MCP-сервера

2. Регистрация инструментов: определение доступных инструментов

3. Обработчики инструментов: реализация логики выполнения инструментов

4. Регистрация ресурсов: определение доступных ресурсов

5. Обработчики ресурсов: реализация логики чтения ресурсов

6. Точка входа: запуск сервера с обменом данными через stdio

Каждый раздел включает подробные встроенные комментарии, объясняющие назначение и использование каждого компонента.

Точки расширения

Добавление инструментов

1. Определите инструмент в list_tools() с его схемой

2. Реализуйте обработчик в call_tool()

3. Для крупных проектов перенесите код в отдельный модуль в директории tools/

Добавление промптов

1. Определите промпт в list_prompts() с его аргументами

2. Реализуйте обработчик в get_prompt()

3. Для крупных проектов перенесите код в отдельный модуль в директории prompts/

Добавление ресурсов

1. Определите ресурс в list_resources() с его метаданными

2. Реализуйте обработчик в read_resource()

3. Для крупных проектов перенесите код в отдельный модуль в директории resources/

Добавление утилит

Вынесите общий код в директорию utils/:

• Функции валидации

• Вспомогательные функции логирования

• Управление конфигурацией

• Утилиты обработки ошибок

Использование в качестве базы

Этот шаблон предназначен для копирования и модификации под новые проекты:

1. Скопируйте всю директорию проекта

2. Переименуйте проект в pyproject.toml

3. Обновите имя сервера в mcp_server.py

4. Добавьте свои инструменты, ресурсы и промпты

5. Настройте документацию по мере необходимости

Используемые модули Python

• mcp.server.Server: основной класс MCP-сервера

• mcp.types.Tool: определение типа инструмента

• mcp.types.Resource: определение типа ресурса

• mcp.types.Prompt: определение типа промпта

• mcp.types.PromptArgument: определение типа аргумента промпта

• mcp.server.stdio: потоки обмена данными через stdio

• asyncio: async/await для параллельных операций

• typing: подсказки типов для ясности кода

Подробные объяснения каждого модуля см. в ARCHITECTURE.md.

Разработка

Запуск тестов

# Run with pytest (add tests first)
uv run pytest

Стиль кода

Этот проект использует подсказки типов Python и следует соглашениям PEP 8. Рекомендуется использовать:

• ruff для линтинга

• mypy для проверки типов

Добавление зависимостей

uv add <package-name>

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

• Ошибка импорта: выполните uv sync для установки зависимостей

• Сервер не отвечает: проверьте конфигурацию MCP-клиента

• Ошибки типов: убедитесь, что установлен Python 3.10+

• Команда uv не найдена: установите uv с https://github.com/astral-sh/uv

Ресурсы

• Спецификация MCP

• MCP Python SDK

• Документация uv

Лицензия

Этот шаблон предоставляется «как есть» в образовательных и ознакомительных целях. Не стесняйтесь использовать и изменять его для своих проектов.