MCP-сервер HR-системы

Неофициальный прототип MCP-сервера, предоставляющий функциональность HR-системы с проверкой токенов Okta. Только для целей оценки и тестирования.

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

Полная документация доступна в папке docs/:

• docs/RAILWAY_README.md — Развертывание на Railway.com (3 шага) 🚀

• docs/DOCKER_QUICK_START.md — Локальный запуск с помощью Docker 🐳

• docs/README_INTEGRATION.md — Использование развернутого сервера 🔌

• docs/CLAUDE.md — Руководство разработчика и архитектура 💻

• docs/INDEX.md — Полный указатель документации 📖

Related MCP server: Insperity MCP Server

Обзор

MCP-сервер HR-системы предоставляет:

• ✅ Поиск информации о сотрудниках

• ✅ Просмотр справочника сотрудников

• ✅ Доступ к информации о заработной плате

• ✅ Управление запросами на отпуск

• ✅ Проверку токенов Okta OAuth 2.0 для всех вызовов инструментов

• ✅ Поддержку потоковой передачи HTTP/NDJSON (FastMCP)

• ✅ Готовность к развертыванию на Railway 🚀

Аутентификация

Этот сервер проверяет токены доступа Okta для всех вызовов инструментов (кроме initialize):

• Источник токена: Сервер авторизации Okta

• Проверка: Подпись JWT, срок действия, проверка аудитории (audience claims)

• Заголовок авторизации: Authorization: Bearer <access_token>

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

# Setup
cp env.example .env
# Edit .env with your Okta credentials

# Install dependencies
pip install -r requirements.txt

# Run in HTTP mode (for Okta MCP Adapter)
python main.py --http 8001

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

.env (Переменные окружения)

OKTA_DOMAIN=ijtestcustom.oktapreview.com
OKTA_AUTHORIZATION_SERVER_ID=auss2fth0mcIXHzVO1d7
OKTA_AUDIENCE=
OKTA_REQUIRED_SCOPES=
# When true (default), tools/list without auth returns 401. When false, allows unauthenticated tools/list (e.g. for gateway registration).
# PROTECTED_DISCOVERY=true

Доступные инструменты

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

Напрямую через VS Code/Copilot

# Endpoint
http://localhost:8001/mcp

# Authorization
Authorization: Bearer <okta_access_token>

Через шлюз Okta MCP Adapter

# Gateway will:
# 1. Receive request from client
# 2. Validate Okta token
# 3. Forward to HR System MCP
# 4. Attach authorization header

Детали реализации

• Фреймворк: FastMCP 3.0.0b1

• Сервер: Uvicorn (асинхронный HTTP)

• Протокол: MCP (Model Context Protocol) с потоковой передачей NDJSON

• Проверка токенов: Проверка JWT на основе JWKS с верификацией подписи

• Кэширование: Ключи JWKS кэшируются с TTL

Поток запросов

Client Request
    ↓
Authorization Header (Okta token)
    ↓
Initialize (no token needed)
    ↓
tools/list (validate token)
    ↓
tools/call (validate token)
    ↓
Response

🚀 Варианты развертывания

Vercel (Serverless) ⚡

Развертывание в виде serverless-функции — автоматическое масштабирование, оплата за использование

• ✅ Лучше всего для: Эпизодического использования, автоматического масштабирования до нуля

• ✅ Бесплатный уровень: 100 ГБ трафика в месяц

• ⚠️ Ограничение: Тайм-аут 10 секунд (бесплатно), 5 минут (Pro)

• 📖 Руководство: docs/VERCEL_README.md

Railway.com (Традиционный сервер) 🚂

Развертывание в виде постоянно работающего сервера — всегда включен, неограниченный тайм-аут

• ✅ Лучше всего для: Постоянного трафика, постоянных соединений

• ✅ Бесплатный уровень: 500 часов в месяц ($5/мес после)

• ✅ Без тайм-аутов: Неограниченная длительность запроса

• 📖 Руководство: docs/RAILWAY_README.md

Docker (Локальная разработка) 🐳

Запуск локально с помощью Docker — полный контроль, тестирование

• 📖 Руководство: docs/DOCKER_QUICK_START.md

docker-compose up -d

Рекомендация:

• Используйте Vercel для эпизодического/непредсказуемого использования (дешевле, автомасштабирование)

• Используйте Railway для постоянного трафика или если требуются длительные тайм-ауты

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

См. docs/RAILWAY_DEPLOYMENT.md для получения полного руководства по устранению неполадок.

Быстрые исправления:

• Ошибка проверки токена: Проверьте OKTA_DOMAIN и OKTA_AUTHORIZATION_SERVER_ID в файле .env

• Порт уже используется: Измените порт в команде запуска: python main.py --http 8002

• Отсутствуют переменные окружения: Скопируйте пример .env и заполните значения

• Ошибка получения JWKS: Проверьте правильность домена Okta и ID сервера авторизации

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

hr-mcp-server/
├── main.py                    # FastMCP server with HTTP handler
├── requirements.txt           # Python dependencies
├── Dockerfile                 # Docker container definition
├── docker-compose.yml         # Docker Compose configuration
├── railway.json               # Railway deployment config
├── deploy-railway.sh          # Deployment helper script
├── test_server.sh            # Server test script
├── auth/                      # Authentication module
│   ├── __init__.py
│   └── okta_validator.py     # Okta token validation
└── docs/                      # Documentation
    ├── INDEX.md              # Documentation index
    ├── RAILWAY_README.md     # Railway quick start
    ├── RAILWAY_DEPLOYMENT.md # Complete deployment guide
    ├── DOCKER_QUICK_START.md # Docker reference
    ├── README_INTEGRATION.md # Usage guide
    ├── CLAUDE_CODE_SETUP.md  # Claude Code setup
    ├── CLAUDE.md             # Developer documentation
    └── ...more docs

См. docs/INDEX.md для получения полного руководства по документации.

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

# Using curl with Okta token
curl -X POST http://localhost:8001/mcp \
  -H "Authorization: Bearer <your_okta_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list",
    "params": {}
  }'

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

Полную документацию см. в папке docs/:

• Начало работы — Указатель документации

• Развертывание на Railway — Руководство по облачному развертыванию

• Запуск с Docker — Локальная разработка

• Руководство по интеграции — Как использовать сервер

• Руководство разработчика — Архитектура и разработка

Ссылки

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

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

• Документация для разработчиков Okta

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

Статус

⚠️ Неофициальный прототип — Только для оценки и тестирования. Не для использования в продакшене.

Лицензия: Apache 2.0