TT-Agent

Локальный MCP-first ассистент для подготовки и отправки worklog'ов в Tempo на основе Git-активности, календаря, Toggl и инцидентов.

Пользовательская установка вынесена в INSTALLATION.md. В этом файле оставлена информация для разработки, отладки и сопровождения проекта.

Статус

Проект находится в MVP-стадии.

Основной runtime-интерфейс — MCP server через stdio. CLI остаётся служебным слоем для локальной отладки, админских операций и проверки отдельных pipeline'ов без внешнего MCP-клиента.

Установка через npm

После публикации пакет можно запускать как локальный MCP stdio server:

npx tt-agent

Или установить глобально:

npm install -g tt-agent
tt-agent

MCP-конфиг для клиента должен запускать бинарь tt-agent. Например:

{
  "mcpServers": {
    "tt-agent": {
      "command": "npx",
      "args": ["tt-agent"]
    }
  }
}

Если нужно явно запускать alias tt-agent-mcp, используйте npm package selector:

npx --package tt-agent tt-agent-mcp

Конфигурация npm-установки

Runtime-конфиг хранится вне npm-пакета, в домашней директории пользователя:

~/.tt-agent/application.yml

Создать дефолтный конфиг можно командой:

npx --package tt-agent tt init

Если пакет установлен глобально:

tt init

После этого откройте ~/.tt-agent/application.yml и внесите токены и настройки. Этот файл локальный, в npm-пакет не входит и не должен попадать в Git.

Минимальные обязательные поля для отправки worklog'ов:

integrations:
  jira:
    enabled: true
    url: "https://your-company.atlassian.net/"
    email: "[email protected]"
    token: "jira-api-token"

  tempo:
    token: "tempo-api-token"
    authorAccountId: "optional-tempo-author-account-id"

При npm-запуске Git-репозитории не нужно монтировать: сервер работает как обычный локальный процесс и читает пути напрямую. Чтобы collector не учитывал чужие коммиты из git log --all, укажите свой Git author name и email. Обычно их можно посмотреть так:

git config --global user.name
git config --global user.email

sources:
  git:
    enabled: true
    authors: ["Your Name"]
    authorEmails: ["[email protected]"]
    repos:
      - path: /Users/you/IdeaProjects/project-a
        name: project-a
      - path: /Users/you/IdeaProjects/project-b
        name: project-b

authors должен совпадать с Git author name, а authorEmails — с Git author email в ваших коммитах. Если оба списка пустые, collector берёт коммиты всех авторов. Collector сканирует git log --all, поэтому видит коммиты не только текущей ветки.

Безопасность конфигурации:

• не храните реальные токены в config/application.yml внутри репозитория
• используйте ~/.tt-agent/application.yml для локальных секретов
• перед публикацией проверяйте npm pack --dry-run
• при случайном попадании токена в файл проекта токен нужно отозвать и выпустить новый

Архитектура

Основной поток:

1. MCP-клиент вызывает tool из src/mcp/server.ts.
2. src/mcp/tools.ts маршрутизирует вызов в core workflow.
3. Collectors собирают события из Git, Calendar, Toggl и incidents.
4. Core слой строит drafts, summary, weekly review или explanation.
5. Submitter отправляет подтверждённые worklog'и в Tempo.

Ключевые каталоги:

• src/mcp — stdio MCP server и tool dispatcher
• src/chat — conversational routing свободного текста
• src/core — доменная логика, drafts, summary, submit-flow, incidents
• src/collectors — сбор данных из источников
• src/sources — registry источников
• src/integrations — внешние клиенты и интеграции
• src/db — SQLite schema и migrations
• src/cli — CLI команды для debug/admin сценариев
• src/tests — Vitest тесты

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

Установить зависимости:

npm install

Собрать TypeScript:

npm run build

Проверить npm-пакет перед публикацией:

npm run pack:dry-run

Запустить тесты:

npm run test

Запустить CLI из исходников:

npm run dev -- chat "что я делал на этой неделе"

После сборки доступен бинарь tt из dist/cli/index.js.

Конфигурация для разработки

Runtime-конфиг хранится в application.yml.

Для Docker Compose файл config/application.yml монтируется в контейнер как:

/home/node/.tt-agent/application.yml

Для локального CLI/debug режима tt init может создать конфиг в:

~/.tt-agent/application.yml

Полная пользовательская схема настройки описана в INSTALLATION.md. Для разработки обычно важно проверить:

• integrations.jira.enabled
• integrations.jira.url
• integrations.jira.email
• integrations.jira.token
• integrations.tempo.token
• integrations.tempo.authorAccountId
• sources.git.enabled
• sources.git.repos
• sources.calendar.enabled
• sources.toggl.enabled
• sources.incidents.enabled
• mcp.debug
• mcp.exposeLowLevel

Docker для разработки

Локальная сборка из исходников запускается через override:

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

Текущий docker-compose.yml:

• поднимает сервис tt-agent
• монтирует config/application.yml
• использует named volume tt-agent-data для data-dir контейнера

Если для Git collector нужны локальные репозитории, добавьте volume mounts в compose-конфиг и укажите соответствующие пути в sources.git.repos.

CLI / Debug

tt chat — основной helper для проверки conversational routing:

tt chat "что я делал на этой неделе"

Он маршрутизирует запрос к подходящему workflow:

• tt_timesheet_today
• tt_timesheet_range
• tt_weekly_review
• tt_explain_draft
• tt_create_incident

Если текст не распознан, CLI возвращает help/clarification. Результат — агрегированный JSON-ответ.

Полезные команды:

tt init
tt config show
tt config set tempo.token YOUR_TEMPO_TOKEN
tt debug prompt today

MCP Tools

Базовые tools, доступные всегда:

• tt_timesheet_today
• tt_timesheet_range
• tt_weekly_review
• tt_explain_draft
• tt_converse
• tt_submit_tempo
• tt_create_incident
• tt_update_draft
• tt_assign_time
• tt_move_time

Toggl tool публикуется только при sources.toggl.enabled: true:

• tt_submit_toggl_to_tempo

Low-level tools скрыты по умолчанию и включаются через mcp.exposeLowLevel: true:

• tt_scan_day
• tt_get_summary
• tt_suggest_worklogs
• tt_rebuild_drafts
• tt_clear_drafts

Основные workflows

tt_timesheet_today:

• сканирует источники за день
• строит worklog drafts
• возвращает summary, summaryText, drafts, draftsCount, readyToSubmit

tt_timesheet_range:

• работает с date, startDate, endDate, period, range, days
• возвращает range summary, issue/project summary, problem days и day reports

tt_weekly_review:

• строит обзор недели или произвольного диапазона
• возвращает summary по issue, project, incidents, meetings и дням

tt_explain_draft:

• объясняет, почему время попало в конкретный Jira issue
• возвращает provenance, confidence, drafts и summaryText

tt_converse:

• принимает свободный текст
• сам выбирает подходящий workflow

Submit и destructive операции

tt_submit_tempo можно вызывать на реальную отправку только после явного подтверждения пользователя:

• dryRun=true не требует реальной отправки
• dryRun=false требует confirm=true

tt_submit_toggl_to_tempo работает аналогично и доступен только при включённом Toggl.

tt_clear_drafts требует:

• userRequested=true
• confirm=true
• destructive=true

tt_rebuild_drafts очищает и пересобирает drafts, поэтому должен вызываться только по явному запросу пользователя.

Draft Editing

tt_update_draft поддерживает операции:

• setDuration (issueKey, minutes)
• setDescription (issueKey, description)
• delete (issueKey)
• split (issueKey, parts)

tt_assign_time назначает timeline block на issue key из обнаруженных за день ключей.

tt_move_time переносит минуты между issue key из обнаруженных за день ключей.

Toggl Import

Toggl Track интеграция опциональна.

Пока sources.toggl.enabled: false, tool tt_submit_toggl_to_tempo не публикуется. Если Toggl включён, импорт читает entries из Toggl Track API v9 за выбранный день, извлекает Jira issue key из description и отправляет их в Tempo после явного confirm=true.

Для импорта в Tempo у Toggl entry должен быть Jira key в description, например:

PROJ-123 описание работы

projectId и tags работают как необязательные фильтры импортируемых Toggl entries.

Тесты

Тесты лежат в src/tests и запускаются через Vitest:

npm run test

Перед изменениями в core workflow желательно запускать весь набор тестов. Для узких правок можно запускать отдельный тест напрямую через Vitest, например:

npx vitest run src/tests/weeklyReview.test.ts

Ограничения MVP

• src/integrations/jiraClient.ts пока не используется основным submit-flow
• low-level MCP tools скрыты по умолчанию и включаются только через mcp.exposeLowLevel: true
• основной сценарий проекта не зависит от локальной LLM