使用说明

YaTracker Connector

Python библиотека и MCP сервер для работы с API Яндекс Трекера.

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

Вариант 1: Docker (Рекомендуется)

Самый простой способ для использования MCP сервера:

# 1. Создайте .env файл
cp config/sample.env .env
# Отредактируйте .env и добавьте свои credentials

# 2. Запустите
docker-compose up -d

# Готово! MCP сервер работает на порту 8080

Преимущества Docker:

✅ Никаких абсолютных путей
✅ Работает везде одинаково
✅ Легко передать коллегам
✅ Не конфликтует с другими проектами

📖 Подробнее: DOCKER.md

Вариант 2: Локальная установка

# 1. Установите зависимости
pip install -r requirements.txt

# 2. Создайте .env
cp config/sample.env .env
# Добавьте YATRACKER_TOKEN и YATRACKER_ORG_ID

# 3. Используйте CLI
PYTHONPATH=src python3.11 -m scripts.cli issues list --queue CRM

📖 Подробнее: QUICKSTART.md

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

QUICKSTART.md - Быстрый справочник команд CLI
CLAUDE.md - Полная инструкция для работы с проектом
DOCKER.md - Развертывание через Docker

🔧 Возможности

CLI (Command Line Interface)

# Список задач
PYTHONPATH=src python3.11 -m scripts.cli issues list --queue CRM --limit 50

# Комментарии
PYTHONPATH=src python3.11 -m scripts.cli comments list CRM-19
PYTHONPATH=src python3.11 -m scripts.cli comments add CRM-19 "Текст"

# Переходы статусов
PYTHONPATH=src python3.11 -m scripts.cli transitions list CRM-19

# Вложения
PYTHONPATH=src python3.11 -m scripts.cli attachments download CRM-19

Python API

from yatracker_connector import (
    build_tracker_client,
    get_issue,
    add_comment,
    search_issues
)

client = build_tracker_client()
issue = get_issue(client, 'CRM-19')
add_comment(issue, 'Текст комментария')

MCP Server для Claude Code

Запустите через Docker и настройте в .mcp.json:

{
  "mcpServers": {
    "yatracker": {
      "transport": "sse",
      "url": "http://localhost:8080/sse"
    }
  }
}

MCP Инструменты

Работа с задачами

yatracker_search_issues - поиск и список задач
yatracker_get_issue - детали задачи
yatracker_create_issue - создать задачу/лид
yatracker_update_issue - обновить поля

Переходы и статусы

yatracker_list_transitions - доступные переходы
yatracker_execute_transition - выполнить переход

Вложения

yatracker_download_attachments - скачать вложения
yatracker_attach_file - прикрепить файл

Метаданные

yatracker_list_queues - список очередей
yatracker_list_queue_fields - поля очереди
yatracker_list_all_fields - все поля системы
yatracker_list_queue_issue_types - типы задач
yatracker_get_queue_workflows - бизнес-процесс/граф статусов

🤝 Для команды

Передача проекта коллегам (Docker):

# 1. Коллега клонирует репозиторий
git clone <url>
cd "YaTracker Connector"

# 2. Создает свой .env
cp config/sample.env .env
# Добавляет свои credentials

# 3. Запускает
docker-compose up -d

Вот и всё! Никаких настроек путей, версий Python и прочего.

🔐 Настройка

Создайте файл .env в корне проекта:

YATRACKER_TOKEN=your_oauth_token_here
YATRACKER_ORG_ID=your_organization_id
# опционально, если ведёшь учёт приложения: YATRACKER_OAUTH_CLIENT_ID=...

Как получить credentials:

Токен OAuth: Яндекс OAuth
Org ID: В Трекере → Администрирование → Организации → идентификатор
Client ID (необязательно): в том же кабинете OAuth — идентификатор приложения; для вызовов API Трекера достаточно токена

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

.
├── Dockerfile              # Docker образ
├── docker-compose.yml      # Простой запуск
├── .env                    # Credentials (НЕ коммитить!)
├── src/yatracker_connector/
│   ├── config.py          # Настройки
│   ├── client.py          # Клиент API
│   └── operations.py      # Операции с задачами
└── scripts/
    ├── cli.py             # CLI интерфейс
    └── mcp_server.py      # MCP сервер

Доступные очереди

CRM - Lead (лиды и клиенты)
DEV - Разработка
MGT - Управление
ISTRA - Истра
ISTRATEST - Istratest
ISTR - Istra

Требования

Python 3.11+
Yandex Tracker API token
Organization ID

Лицензия

MIT