myteam-mcp

MCP-сервер (Model Context Protocol) для HR-платформы «МояКоманда» (моякоманда.рф). Даёт AI-ассистентам (Claude и другим MCP-клиентам) доступ к сущностям и действиям HR-платформы через её REST API: сотрудники, команды, календарь и отсутствия, заявки, база знаний, опросы, новости и геймификация.

Не путать с мессенджером VK Teams / Myteam (mail.ru) — это другой продукт с другим API.

Возможности

• Два транспорта: stdio (локально, у каждого свой токен) и http (Streamable HTTP, один общий сервер на пространство с проброской авторизации per-request).
• ~30 курируемых инструментов по основным HR-сценариям + универсальный myteam_request для доступа к любому из ~2900 методов API.
• Безопасность по умолчанию: изменяющие операции и «сырой» доступ к API выключены и включаются явными флагами.
• Права ролей соблюдаются автоматически — API отдаёт данные в рамках роли пользователя, которому принадлежит токен.
• Готовые Docker-образ и Helm-чарт.

Как это работает

Авторизация в «МояКоманда» — Laravel Sanctum. Токен получается методом POST /api/login-mobile (email/телефон + пароль) и передаётся во всех запросах заголовком Authorization: Bearer <token>. Базовый адрес — домен вашего тенанта (например https://company.ismyteam.ru), все методы под префиксом /api. Swagger доступен внутри пространства по адресу /api-docs.

Установка

git clone https://github.com/pohodnya/myteam-mcp.git
cd myteam-mcp
npm install
npm run build

Требуется Node.js >= 20.

Получение токена

npm run login -- https://company.ismyteam.ru user@company.ru 'ваш-пароль'
# выведет токен в stdout

или задайте MYTEAM_BASE_URL, MYTEAM_LOGIN, MYTEAM_PASSWORD и запустите npm run login.

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

Переменная	Обязательна	Описание
MYTEAM_BASE_URL	да	URL тенанта, напр. https://company.ismyteam.ru
MYTEAM_TOKEN	для stdio	Bearer-токен API. В http может приходить per-request
MYTEAM_TRANSPORT	нет	stdio (по умолчанию) или http
MYTEAM_HTTP_HOST / MYTEAM_HTTP_PORT	нет	Хост/порт http-транспорта (0.0.0.0 / 3000)
MYTEAM_ENABLE_WRITE	нет	true — разрешить изменяющие операции
MYTEAM_ENABLE_RAW	нет	true — включить инструмент myteam_request
MYTEAM_TIMEOUT_MS	нет	Таймаут запросов, мс (30000)

Запуск в Claude Desktop / Claude Code (stdio)

{
  "mcpServers": {
    "myteam": {
      "command": "node",
      "args": ["/абсолютный/путь/myteam-mcp/dist/index.js"],
      "env": {
        "MYTEAM_BASE_URL": "https://company.ismyteam.ru",
        "MYTEAM_TOKEN": "ваш-токен"
      }
    }
  }
}

Общий сервер с проброской авторизации (http)

Один инстанс на всё пространство; токен не хранится на сервере, а берётся из заголовка Authorization каждого запроса — каждый пользователь работает под своей ролью.

MYTEAM_BASE_URL=https://company.ismyteam.ru MYTEAM_TRANSPORT=http npm start

curl -X POST http://localhost:3000/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'Authorization: Bearer <токен-пользователя>' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Health-check без авторизации: GET /health.

OAuth 2.1 мост (per-user авторизация для коннекторов)

У «МояКоманда» нет OAuth — только логин по email/паролю. Чтобы работать с коннекторами claude.ai (которым нужен OAuth 2.1 + Dynamic Client Registration), сервер умеет сам выступать Authorization Server: показывает форму входа, аутентифицирует пользователя через /api/login-mobile и выдаёт собственный access_token (зашифрованный Sanctum-токен). На /mcp токен расшифровывается обратно.

Включение:

MYTEAM_BASE_URL=https://company.ismyteam.ru \
MYTEAM_TRANSPORT=http \
MYTEAM_ENABLE_OAUTH=true \
MYTEAM_OAUTH_SECRET='случайная-строка-не-короче-16-символов' \
MYTEAM_PUBLIC_URL=https://mcp.company.ru \
npm start

Реализовано: Authorization Code + PKCE (S256), DCR (POST /register), метаданные /.well-known/oauth-authorization-server и /.well-known/oauth-protected-resource, 401 с заголовком WWW-Authenticate на /mcp. Коды и токены self-contained (AES-256-GCM), серверное состояние не хранится — мост работает в stateless-режиме и масштабируется.

В коннекторе claude.ai укажите URL https://mcp.company.ru/mcp — остальное (discovery, регистрация, вход) пройдёт автоматически. Каждый пользователь входит под своей учётной записью и работает в рамках прав своей роли.

Header-passthrough (без OAuth) остаётся доступным одновременно: если в заголовке пришёл «сырой» Sanctum-токен, он используется напрямую.

Инструменты

Система: get_company_info, whoami, healthz Сотрудники и команды: list_users, search_users_by_filter, get_user, get_user_work, get_user_subordinates, list_teams, get_team, get_team_structure Календарь и отсутствия: list_calendar_events, list_absences, who_is_absent, memorable_dates Заявки: list_requests, get_request, requests_catalog, requests_need_action База знаний: search_knowledge_base, list_kb_categories, get_kb_article Опросы: list_surveys, get_survey, get_survey_participants, get_survey_questions, get_survey_statistics, list_survey_templates ИПР (развитие): list_development_plans, my_development_plans, get_user_development_plans, get_development_plan Эффективность: list_evaluations, get_evaluation, get_evaluation_participants, get_evaluation_user_card, get_evaluation_matrix (9-Box), list_kpi, get_kpi, get_kpi_user_info Вовлечённость: get_news_feed, get_my_activities, get_rating, get_prize_store, get_user_thanks

Изменяющие (MYTEAM_ENABLE_WRITE=true): create_calendar_event, send_thanks, share_coins, run_development_plan, set_development_material_status, save_kpi_progress, submit_evaluation_answer, complete_evaluation, answer_survey_question, publish_survey, remind_survey_participants Расширенный (MYTEAM_ENABLE_RAW=true): myteam_request — произвольный вызов любого эндпоинта /api/...

Docker

docker build -t myteam-mcp .
docker run --rm -p 3000:3000 \
  -e MYTEAM_BASE_URL=https://company.ismyteam.ru \
  myteam-mcp

По умолчанию образ стартует в http-режиме с проброской токена.

Helm

helm install myteam-mcp ./helm/myteam-mcp \
  --set config.baseUrl=https://company.ismyteam.ru

По умолчанию token.passthrough=true (per-request). Для общего токена:

helm install myteam-mcp ./helm/myteam-mcp \
  --set config.baseUrl=https://company.ismyteam.ru \
  --set token.passthrough=false \
  --set token.existingSecret=my-secret

Разработка

npm run dev          # watch-режим (stdio)
npm test             # тесты (vitest)
npm run test:coverage
npm run typecheck

Архитектура

src/
  index.ts      точка входа, выбор транспорта
  config.ts     конфигурация из ENV
  client.ts     HTTP-клиент REST API (Bearer, таймауты, ошибки)
  auth.ts       логин через /api/login-mobile
  server.ts     фабрика MCP-сервера, регистрация инструментов
  http.ts       Streamable HTTP транспорт с проброской токена
  login.ts      CLI получения токена
  tools/        инструменты по модулям

Лицензия

MIT