39 lines
4.2 KiB
Markdown
39 lines
4.2 KiB
Markdown
# t3code-mcp
|
||
|
||
MCP-коннектор к серверам [T3 Code](https://github.com/pingdotgg/t3code) (`архитектура.md` §5): диспетчер бобра запускает кодинг-треды на маке и на dell, ждёт их и читает результат. Ни шелла, ни терминала - только оркестрация по HTTP API T3 (`packages/contracts/src/environmentHttp.ts`).
|
||
|
||
## Тулзы
|
||
|
||
| Тулза | Что делает |
|
||
|---|---|
|
||
| `t3_machines()` | машины из конфига, кто сейчас online (`/.well-known/t3/environment`), allowlist проектов |
|
||
| `t3_projects(machine)` | проекты машины, прошедшие allowlist: путь, модель по умолчанию, число тредов |
|
||
| `t3_dispatch(machine, project, prompt, title?, model?, thread_id?)` | `thread.create` + `thread.turn.start` (или только `turn.start` в существующий тред) → `thread_id` сразу |
|
||
| `t3_thread(thread_id, turns?)` | состояние без ожидания: тёрн, сессия, последние сообщения, тулзы, файлы, `pending` (вопрос/аппрув) |
|
||
| `t3_wait(thread_id, timeout?)` | блокируется до `completed` / `interrupted` / `error`, вопроса или таймаута; та же вьюха |
|
||
| `t3_answer(thread_id, answers)` | `thread.user-input.respond` на висящий вопрос треда (`answers`: id вопроса → label, список для multi_select) |
|
||
| `t3_interrupt(thread_id)` | `thread.turn.interrupt` |
|
||
|
||
## События
|
||
|
||
Коннектор держит WS-подписку `orchestration.subscribeShell` на каждую машину (Effect RPC поверх JSON: `Request` → `Chunk` + `Ack`, `Ping` раз в 20 с, реконнект с `afterSequence`, снапшот при реконнекте переигрывает пропущенное). Треды, запущенные через `t3_dispatch`, отслеживаются (`T3CODE_MCP_STATE`, json на volume); переходы `running → completed/interrupted/error` и появление вопроса (`hasPendingUserInput`) превращаются в события `completed` / `interrupted` / `failed` / `question` и уходят `POST` в `T3CODE_MCP_HOOK_URL` (gateway `/hooks/t3code`, bearer `T3CODE_MCP_GATEWAY_TOKEN`, scope `api`) через persisted outbox с ретраями. Gateway делает из события инжект в мастер (`beaver-agent/config.py`, job `t3code`).
|
||
|
||
`t3_wait` - обычный долгий вызов, не MCP Task: Claude Code расширение Tasks не поддерживает, зато сам уводит вызов дольше двух минут в фоновую задачу (`CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS`). Треды бегут в `full-access` без аппрувов; тред ищется по всем машинам, если коннектор перезапускался.
|
||
|
||
## Конфиг
|
||
|
||
`t3code.toml` (путь - `T3CODE_MCP_CONFIG`, в образе `/config/t3code.toml`), пример - `t3code.example.toml`. Токены - только из env (`token_env`), выпускаются на каждой машине: `t3 auth session issue --token-only --ttl 365d --label beaver-t3code-mcp`. `projects` - fnmatch по названию и по workspace root; что не совпало, для диспетчера не существует. Порт и адрес - `T3CODE_MCP_HOST` / `T3CODE_MCP_PORT` (8000, путь `/mcp`, `/healthz`).
|
||
|
||
## Разработка
|
||
|
||
```sh
|
||
make sync # uv sync
|
||
make check # ruff format --check, ruff check (ALL), ty, pytest
|
||
make run # T3CODE_MCP_CONFIG=... uv run python -m t3code_mcp
|
||
uv run python scripts/smoke.py http://127.0.0.1:8000/mcp mac t3-smoke # живой диспатч + ожидание
|
||
```
|
||
|
||
## Деплой
|
||
|
||
Сервис `t3code-mcp` в `beaver-agent/docker-compose.yml` (профиль `t3`), образ собирается из этой репы (`T3CODE_MCP_REF`), gateway подключает его как `McpServer.http(name="t3code", url="http://t3code-mcp:8000/mcp")` и отдаёт только диспетчеру.
|