SkillMCP (Система управления навыками)

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

Обзор и мотивация

AI-агенты полагаются на доменные навыки (инструкции, метаданные, схемы и справочные ресурсы) для выполнения сложных инженерных и аналитических задач. Одако управление навыками в разнородных командах и флотах агентов часто создаёт критические эксплуатационные проблемы:

• Фрагментированные и устаревшие навыки: Навыки, хранящиеся в разрозненных отдельных репозиториях или копируемые вручную, быстро выходят из синхронизации, из-за чего агенты выполняют устаревшие или несовместимые рабочие процессы.

• Узкие места при распространении и обновлении: Распространение обновлений навыков по распределённым экземплярам агентов треует ручной синхронизации или хрупких операций копирования файлов.

• Отсутствие версионирования и сложности диагностики: Когда навыки редактируются без неизменяемого версионирования, диагностика регрессий или изменений поведения агентов становится практически невозможной.

• Ограничения масштабируемости одного хоста: Традиционные MCP-серверы на основе stdio привязаны к процессам одного локального хоста, что блокирует горизонтальное масштабирование и высокую доступность.

SkillMCP решает эти задачи, предоставляя централизованную, контейнеризированную и горизонтально масштабируемую систему упавления навыками на базе Stateless Streamable HTTP (с обратно совместимой поддержкой SSE).

Related MCP server: skilldb-mcp

Ключевые возможности и функции

1. Централизованная и версионированная упаковка навыков

• Неизменяемые контейнерные релизы: Навыки (SKILL.md, references/ и examples/) упаковываются непосредственно в Docker-образы с явными semver-тегами (v1.2.0), что обеспечивает 100% воспроизводимость окружений и аудируемость.

• Единый репозиторий навыков: Устраняет рассинхронизацию множества разрозненных репозиториев, управляя, проверяя и объединяя все доменные навыки в одном поддерживаемом репозитории.

• Быстрая диагностика и трассируемость: Версионированные теги контейнеров позволяют легко диагностировать проблемы агентов, воспроизводить историческое поведение и мгновенно откатывать изменения.

2. Stateless MCP поверх Streamable HTTP (горизонтальное масштабирование)

• Настоящая stateless-архитектура запрос/ответ: Streamable HTTP использует стандартные HTTP POST-запросы, при которых экземпляры бэкенда не поддерживают долгоживущее состояние сокетов в памяти между вызовами клиентов.

• Отвязка от сессий и горизонтальное масштабирование: Отдельные запросы могут направляться на любую реплику бэкенд-контейнера за обратным прокси Nginx или балансировщиком нагрузки без необходимости sticky-сессий.

• Кратковременная потоковая передача: Ответы, требующие потоковой передачи, переводятся в text/event-stream только на время передачи конкретного payload и немедленно закрываются после завершения JSON-RPC-ответа.

• Совместимость с унаследованным SSE: Поддерживает устаревшие Server-Sent Events (/sse) с настроенным обходом буферизации прокси (proxy_buffering off) и увеличенными таймаутами чтения для клиентов, требующих постоянных каналов.

• Балансировка нагрузки на Nginx Ingress: Настроена с использованием маршрутизации least_conn, пула keepalive-соединений и выделенных проверок здоровья /healthz для rolling-обновлений без простоев.

[!WARNING] Транспорт и горизонтальное масштабирование:

• Streamable HTTP (default, рекомендуется): Полностью stateless. Допускает горизонтальное автомасштабирование и произвольную балансировку нагрузки между репликами без привязки к сессии.

• Нативный SSE (SKILLMCP_TRANSPORT=sse): Stateful из-за постоянной привязки к TCP-потоку. В режиме нативного SSE горизонтальное масштабирование за стандартными балансировщиками round-robin/least-connections приведёт к ошибкам маршрутизации POST /messages, если не используются sticky-сессии (например, Nginx ip_hash или cookie-аффинити) или развёртывание с одной репликой.

3. Инструменты для разработчиков и агентов

• Встроенный CLI-валидатор навыков: skillmcp validate ./skills автоматически проверяет структуры каталогов, YAML-frontmatter и ссылки на ресурсы перед упаковкой.

• Динамическое обнаружение и поиск:

  • MCP Tools: list_skills, get_skill, search_skills, read_skill_reference, read_skill_example.

  • MCP Resources: skill://{name} для прямого просмотра markdown-документов.

• Два Compose-окружения: docker-compose.local.yml для мгновенной локальной разработки с hot reload через подключаемые тома и docker-compose.yml для продакшн-развёртываний.

• Стандарт TREM для Python: Построен строго в соответствии с принципами Testable, Readable, Extensible, Maintainable (TREM) с использованием uv, pydantic-settings, стандартной библиотеки logging и pytest.

• Автоматическая публикация через CI/CD: Конвейер GitHub Actions, который прогоняет тесты и публикует неизменяемые semver-релизы в Docker Hub по тегам версий (v*.*.*).

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

Предварительные требования

• Python 3.11+

• uv

• Docker и Docker Compose

Локальная установка

# Sync dependencies
uv sync

# Run tests
uv run pytest -v

# Validate skills
uv run skillmcp validate ./skills

# List discovered skills
uv run skillmcp list --skills-path ./skills

Запуск сервера локально

# Start MCP server directly (Streamable HTTP on port 8000)
uv run skillmcp serve --host 0.0.0.0 --port 8000

Docker-топологии

Локальная разработка (Live Reload и Ingress)

docker compose -f docker-compose.local.yml up -d --build

• Nginx Ingress: http://localhost:8080 (проверка здоровья /healthz)

• Бэкенд-приложение: http://localhost:8000 (проверка здоровья /healthz)

Продакшн-развёртывание

docker compose up -d

Тестовые швы

• Шов 1: доменный сервис: tests/test_domain_service.py (проверяет сканер, парсер, безопасность обхода и движок запросов)

• Шов 2: протокол MCP и инструменты: tests/test_mcp_server.py и tests/test_mcp_http.py (проверяют инструменты FastMCP, ресурсы и транспортные маршруты ASGI)

• Шов 3: CLI и интеграция: tests/test_cli.py (проверяет команды CLI: validator, list и serve)