Salary MCP Server (salary-mcp)

Сервер Model Context Protocol (MCP), предоставляющий LLM прямой программный доступ к реальным публичным зарплатным бенчмаркам IT-рынка из Djinni (djinni.co) и DOU (jobs.dou.ua/salaries/).

⚡ Быстрый старт (опубликованный пакет на PyPI)

salary-mcp опубликован на PyPI и может быть запущен мгновенно, без ручного клонирования репозитория.

1. Запуск через Stdio (по умолчанию)

Стандартный ввод/вывод для настольных AI-клиентов (Claude Desktop, Cursor, Antigravity, Zed):

# Instant run with uvx (no installation needed)
uvx salary-mcp

# Or with pipx
pipx run salary-mcp

# Or install via pip
pip install salary-mcp
salary-mcp

2. Запуск через HTTP / SSE (удалённый сервер)

Режим Server-Sent Events (SSE) для удалённых развёртываний, контейнеров и веб-клиентов:

# Start SSE HTTP server on port 8000
uvx salary-mcp --transport sse --host 0.0.0.0 --port 8000

Ваш MCP-клиент может подключиться к: http://localhost:8000/sse

Related MCP server: PayHub MCP Server

🔌 Конфигурации MCP-клиентов

Claude Desktop (claude_desktop_config.json)

Режим Stdio (рекомендуется):

{
  "mcpServers": {
    "salary-mcp": {
      "command": "uvx",
      "args": ["salary-mcp"]
    }
  }
}

Режим HTTP / SSE:

{
  "mcpServers": {
    "salary-mcp": {
      "url": "http://localhost:8000/sse"
    }
  }
}

Cursor (~/.cursor/mcp.json)

{
  "mcpServers": {
    "salary-mcp": {
      "command": "uvx",
      "args": ["salary-mcp"]
    }
  }
}

🌐 Источники данных и архитектура извлечения

Сервер получает данные исключительно с действующих официальных веб-порталов Djinni и DOU:

1. Djinni (https://djinni.co/salaries/)

• Формат эндпоинта: https://djinni.co/salaries/?category={category}&exp={exp}&english_level={level}

• Метод извлечения: скрапинг в реальном времени по запросу скользящих 30-дневных метрик найма платформы Djinni.

• Извлекаемые данные:

  • Ожидания кандидатов: зарплатные ожидания между 25-м и 75-м перцентилями и рассчитанная медиана.

  • Вакансии компаний: диапазоны зарплатных предложений в активных вакансиях.

  • Активность рынка: счётчики в реальном времени активных онлайн-кандидатов и открытых вакансий.

  • Распределение зарплат: полная гистограмма зарплатных корзин, извлечённая напрямую из данных встроенных графиков.

2. DOU (https://jobs.dou.ua/salaries/)

• Источник эндпоинта: основной набор данных виджета, напрямую загружаемый страницей https://jobs.dou.ua/salaries/ (https://s.dou.ua/files/lenta/salary-widget_jun_2026_v3/data/swd-medians.csv).

• Метод извлечения: извлекает срезы официальных статистических квартилей ($q1$, $median$, $q3$), размеры выборок респондентов ($count$) и уровни грейдов ($title$).

• Поддержка исторических данных: доступны запросы к конкретным историческим волнам опросов через параметр as_of_date (например, '2025-12', '2026-06'); по умолчанию используется последняя доступная волна.

❓ Почему данные провайдера DOU могут отличаться от того, что показывает веб-интерфейс сайта

При запросах к DOU через salary-mcp вы можете иногда замечать небольшие различия между возвращаемой статистикой и тем, что отображается в интерактивном интерфейсе jobs.dou.ua/salaries/:

1. Пороговые значения размера выборки во фронтенде:

   • На публичном сайте скрипты построения графиков DOU часто применяют минимальный порог размера выборки (обычно $\ge 15-20$ респондентов).

   • Когда в конкретной группе по опыту респондентов меньше (например, $11$ респондентов для 9 лет опыта в Data Science), график на сайте скрывает или затеняет столбец с пометкой "Недостатньо анкет" (недостаточно данных).

   • Базовый аналитический набор данных DOU сохраняет точное рассчитанное значение медианы для этих респондентов, которое salary-mcp возвращает корректно.

2. Агрегация категорий и фильтрация по конкретной должности:

   • Выбор широкой категории (например, "Data & Analytics" или "Management") в веб-интерфейсе агрегирует все суброли вместе.

   • Запросы по конкретным должностям (например, Middle Data Scientist или Junior HR Specialist) сопоставляются с конкретным уровнем должности в наборе данных.

3. Выпуски волн опросов:

   • По умолчанию salary-mcp всегда выбирает самую последнюю официальную волну опроса (например, 2026-06). Если веб-интерфейс сайта отображает более раннюю волну или другую статью, указание as_of_date обеспечивает полное соответствие.

🛠️ Справочник MCP-инструментов

get_djinni_salaries

Получает из Djinni зарплатные ожидания кандидатов и распределения зарплатных предложений по вакансиям в реальном времени.

• Аргументы:

  • role (string, required): целевая роль (например, "Software Engineer", "QA", "DevOps", "HR").

  • specialization (string, optional): технология или область (например, "Python", "React", "HR").

  • experience_years (integer, optional): годы опыта (например, 0, 2, 5).

  • english_level (string, optional): уровень владения английским (например, "intermediate", "advanced").

get_dou_salaries

Получает из DOU официальные бенчмарки и перцентили зарплатных опросов.

• Аргументы:

  • role (string, required): роль или категория (например, "Software Engineer", "Data Science").

  • specialization (string, optional): язык или суброль (например, "Python", "Data Scientist").

  • experience_years (integer, optional): годы профессионального опыта.

  • seniority (string, optional): уровень грейда ("Junior", "Middle", "Senior", "Lead", "Architect").

  • city (string, optional): фильтр по локации (например, "Kyiv", "Lviv", "Remote").

  • as_of_date (string, optional): дата опроса в формате YYYY-MM (например, "2025-12", "2026-06"). По умолчанию — последняя доступная.

compare_salaries

Сравнивает зарплатные бенчмарки Djinni и DOU бок о бок с дифференциальным анализом.

• Аргументы:

  • role (string, required): целевая роль.

  • specialization (string, optional): технология или специализация.

  • experience_years (integer, optional): годы опыта.

  • seniority (string, optional): уровень грейда для сопоставления с DOU.

  • as_of_date (string, optional): целевая дата опроса для сравнения с DOU.

list_specializations

Выводит список доступных ролей, технологий, грейдов, локаций и исторических дат опросов.

• Аргументы:

  • provider (string, optional): область выбора ("all", "djinni", "dou"). По умолчанию — "all".

🛠️ Локальная разработка

# Clone and install dependencies
git clone https://github.com/propsi4/salary-mcp.git
cd salary-mcp
poetry install

# Run test suite
poetry run pytest

# Run linter and type checks
poetry run ruff check . --fix
poetry run ruff format .
poetry run mypy src tests

📄 Лицензия

Лицензия MIT. Подробности см. в LICENSE.