MCP Template

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

Описание

Этот репозиторий представляет собой шаблон для создания серверов Model Context Protocol (MCP). Шаблон включает в себя базовую структуру, примеры обработчиков, middleware для логирования и метрик, а также все необходимые компоненты для быстрого старта разработки собственных MCP-инструментов.

Особенности

• Базовая структура MCP-сервера с поддержкой инструментов
• Middleware для логирования и сбора метрик
• Готовые эндпоинты для мониторинга и проверки состояния
• Поддержка конфигурации через флаги командной строки и переменные окружения
• Совместимость с протоколом Model Context Protocol (MCP)

Установка

1. Убедитесь, что у вас установлен Go 1.25 или выше
2. Клонируйте репозиторий:

git clone https://git.ymnuktech.ru/ymnuk/mcp-template.git
cd mcp-template

3. Переименуйте модуль в go.mod под ваш проект:

go mod edit -module your-project-name

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

go mod download

5. Соберите проект:

go build .

Конфигурация

Сервер поддерживает следующие параметры конфигурации:

Параметр	Флаг	Переменная окружения	По умолчанию	Описание
Port	-p, --port	WEB_PORT	3000	Порт для входящих соединений

Использование

Запустите MCP сервер:

./mcp-template

Или с настройкой параметров:

./mcp-template --port 3001

Или с использованием переменных окружения:

WEB_PORT=3001 ./mcp-template

Сервер будет доступен по адресу http://localhost:3000/mcp

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

mcp-template/
├── main.go                 # Основной файл приложения
├── go.mod                  # Модуль Go
├── config/                 # Конфигурация приложения
│   └── config.go
├── handler/                # Обработчики HTTP-запросов и MCP-инструментов
│   ├── example.go          # Пример MCP-инструмента
│   └── health.go           # Эндпоинт проверки состояния
└── middleware/             # Middleware для логирования и метрик
    ├── mddleware.go        # Middleware для логирования
    └── metrics.go          # Middleware для сбора метрик

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

Для добавления нового MCP-инструмента:

1. Создайте новый файл в директории handler/ с вашим инструментом, например mytool.go
2. Реализуйте функцию обработчика MCP в соответствии с примером в example.go
3. Добавьте инструмент в main.go, используя функцию mcp.AddTool:

mcp.AddTool(server, &mcp.Tool{
    Name:        "myToolName",
    Description: "Описание вашего инструмента, которое поможет LLM понять его назначение",
}, handler.MyToolHandler)

Middleware

Шаблон включает в себя следующие middleware:

• Логирование: Записывает все HTTP-запросы и ответы с детальной информацией
• Метрики: Собирает Prometheus-метрики для мониторинга производительности

Мониторинг

Сервер предоставляет метрики в формате Prometheus по адресу /metrics. Доступны следующие метрики:

HTTP-метрики

• http_requests_total - Общее количество HTTP-запросов с разбивкой по методу, пути и статусу
• http_request_duration_seconds - Гистограмма времени выполнения HTTP-запросов

Метрики MCP инструментов

• mcp_tool_calls_total - Общее количество вызовов MCP инструментов с разбивкой по имени инструмента и статусу (успешно/ошибка)
• mcp_tool_call_duration_seconds - Гистограмма времени выполнения вызовов MCP инструментов

Процессные метрики

• process_cpu_seconds_total - Общее время CPU, затраченное процессом (включает пользовательское и системное время) - стандартная метрика Go-рантайма
• process_resident_memory_bytes_custom - Объем резидентной памяти процесса в байтах (кастомная метрика)

Эндпоинты

Сервер предоставляет следующие HTTP-эндпоинты:

• /mcp - основной endpoint для MCP-инструментов
• /metrics - endpoint для сбора Prometheus-метрик
• /health - endpoint для проверки состояния сервиса (возвращает HTTP 200 OK)

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

Для запуска тестов:

go test ./...

Лицензия

Этот проект распространяется под лицензией, подробности см. в файле LICENSE.