# 1C Testpilot

MCP-сервер для работы AI-агентов с интерфейсом **1С:Предприятия**. Позволяет агенту
открывать формы, читать и изменять данные, работать с таблицами, записывать и воспроизводить
сценарии действий.

Сервер подключается напрямую к локальному или удалённому клиенту тестирования 1С
по его сетевому протоколу.

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

- Подключение к локальному или удалённому тест-клиенту по адресу и порту; порядок подключения
  определяется автоматически.
- Запуск/останов тест-клиента 1С на компьютере MCP-сервера (файловая или серверная база, логин/пароль) с ожиданием
  готовности и авто-подключением — `tc_session(action="launch_client"/"stop_client")`.
- Навигация по дереву UI: активное окно → форма → элементы (по иерархическим ключам).
- Чтение: значения полей, вид/класс/заголовки элементов, таблицы, области табличного документа.
- Действия: ввод текста/HTML, клики, флажки, выбор из списков/меню, работа с таблицами и деревом,
  календарь, гиперссылки, навигация по строкам и окнам.
- **Запись и воспроизведение сценариев** (uilog): агент выполняет шаги → получает XML-сценарий →
  воспроизводит его. Два режима записи (см. [переменные окружения](#переменные-окружения)).
- 10 инструментов по типам объектов клиента тестирования; конкретная операция выбирается
  параметром `action` (136 действий). Версионный гейтинг по целевой версии платформы.

## Требования

- Windows или Linux для MCP-сервера. Платформа 1С (напр. 8.3.27 или 8.5.1)
  нужна на компьютере тест-клиента.
- Python 3.10+.
- Тест-клиент 1С — либо поднимается действием `tc_session(action="launch_client")`, либо запускается заранее:
  `1cv8.exe ENTERPRISE /F"<база>" /TESTCLIENT -TPort <порт>`

## Установка

Установка из репозитория GitHub. Нужны Git и [pipx](https://github.com/pypa/pipx#install-pipx).

```bash
pipx install git+https://github.com/ROCTUP/1c-testpilot.git
pipx ensurepath
```

После установки перезапустите терминал и MCP-клиент, чтобы они увидели команду `1c-testpilot`.
Зависимости устанавливаются автоматически в отдельное окружение.

Если репозиторий уже скачан, установите проект из его корневой папки:

```bash
pipx install .
```

## Подключение к MCP-клиенту

Выберите способ подключения: **stdio** — MCP-клиент сам запускает 1C Testpilot;
**Streamable HTTP** — вы запускаете сервер отдельно, а MCP-клиент подключается по URL.

### Через stdio

Команда `1c-testpilot` должна быть доступна в `PATH` MCP-клиента. Если клиент её не находит,
укажите в `command` полный путь к исполняемому файлу.

**Claude Desktop** ([документация](https://support.claude.com/en/articles/10949351-getting-started-with-local-mcp-servers-on-claude-desktop)).
Откройте **Settings → Developer → Edit Config** и добавьте сервер в `mcpServers`:

- Windows: `%APPDATA%\Claude\claude_desktop_config.json`.
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`.

```json
{
  "mcpServers": {
    "1c-testpilot": {
      "command": "1c-testpilot",
      "env": { "TC1C_TRANSPORT": "stdio" }
    }
  }
}
```

После изменения файла полностью перезапустите Claude Desktop.

**Claude Code** ([документация](https://code.claude.com/docs/en/mcp)):

```bash
claude mcp add --env TC1C_TRANSPORT=stdio --transport stdio --scope user 1c-testpilot -- 1c-testpilot
```

`--scope user` делает сервер доступным во всех проектах. Состояние подключения можно
посмотреть командой `/mcp` внутри Claude Code.

**Codex** ([документация](https://developers.openai.com/codex/mcp/)).
Добавьте в `~/.codex/config.toml`:

```toml
[mcp_servers.1c-testpilot]
command = "1c-testpilot"
env = { TC1C_TRANSPORT = "stdio" }
```

Или добавьте сервер через CLI:

```bash
codex mcp add 1c-testpilot --env TC1C_TRANSPORT=stdio -- 1c-testpilot
```

Состояние подключения — `/mcp` в Codex. Для длительных операций, например запуска 1С,
можно добавить `tool_timeout_sec = 120` в секцию сервера; стандартный таймаут Codex — 60 секунд.

Без установки пакета можно указать напрямую: `"command": "python", "args": ["<путь>/app/server.py"]`.

### Через Streamable HTTP

Запустите 1C Testpilot в отдельном терминале.

**Windows, PowerShell:**

```powershell
$env:TC1C_TRANSPORT = "streamable-http"
$env:TC1C_HTTP_HOST = "127.0.0.1"
$env:TC1C_HTTP_PORT = "6004"
$env:TC1C_HTTP_PATH = "/mcp"
1c-testpilot
```

**Linux, Bash:**

```bash
TC1C_TRANSPORT=streamable-http TC1C_HTTP_HOST=127.0.0.1 TC1C_HTTP_PORT=6004 TC1C_HTTP_PATH=/mcp 1c-testpilot
```

Пока сервер работает, он принимает MCP-подключения по адресу `http://127.0.0.1:6004/mcp`.
Настройки `TC1C_*` задаются в окружении этого процесса сервера.

**Claude Code:**

```bash
claude mcp add --transport http --scope user 1c-testpilot http://127.0.0.1:6004/mcp
```

Эта настройка работает и в локальных сессиях вкладки **Code** приложения Claude Desktop:
они используют MCP-конфигурацию Claude Code. Подключение к HTTP-серверу выполняется напрямую.
[Документация Claude Code Desktop](https://code.claude.com/docs/en/desktop#shared-configuration).

Если сервер с таким именем уже добавлен через stdio, сначала удалите прежнюю запись
командой `claude mcp remove --scope user 1c-testpilot`.

**Codex** — используйте URL в секции сервера в `~/.codex/config.toml`:

```toml
[mcp_servers.1c-testpilot]
url = "http://127.0.0.1:6004/mcp"
```

При переходе со stdio замените прежние `command`, `args` и `env` на `url`.
Для новой записи можно использовать CLI:

```bash
codex mcp add 1c-testpilot --url http://127.0.0.1:6004/mcp
```

Для подключения с другого компьютера задайте `TC1C_HTTP_HOST` равным сетевому IP компьютера
с 1C Testpilot и укажите этот IP в URL клиента. Порт `6004` должен быть доступен из сети клиента.
Встроенной HTTP-аутентификации в 1C Testpilot нет; доступ к серверу ограничивается вашей сетью
или внешним прокси с аутентификацией и HTTPS.

Также поддерживается прежний транспорт **SSE**: `TC1C_TRANSPORT=sse`, адрес подключения
`http://127.0.0.1:6004/sse`. У него стандартные пути `/sse` и `/messages/`;
`TC1C_HTTP_PATH` применяется только к Streamable HTTP.

### Подключение к клиенту тестирования 1С

Адрес, порт и версия платформы 1С передаются инструменту `tc_session` при выполнении
действия `connect`. Эти параметры относятся к клиенту тестирования 1С и не задаются
в конфигурации подключения MCP. Запуск клиента выполняется действием `launch_client`.

- При локальном подключении `host` можно опустить: по умолчанию `127.0.0.1`.
- Удалённый клиент запустите с `/TESTCLIENT -TPort <порт>`; его порт должен быть доступен
  с компьютера MCP-сервера.
- `launch_client` и `stop_client` работают на компьютере MCP-сервера. На Linux для запуска
  клиента нужен графический сеанс; для подключения к уже запущенному — не нужен.
- Можно работать с несколькими базами или одной базой под разными пользователями.
  Подключение выбирается через `connection_id`, список — `tc_session(action="list_connections")`.

## Переменные окружения

Задаются в окружении процесса сервера (см. [.env.example](.env.example)):

- `TC1C_CONNECTION_LIMIT` — максимум зарегистрированных подключений, по умолчанию `16`.
  Отключённый клиент, запущенный сервером, учитывается до `stop_client`. Лимит ссылок
  `TC1C_REF_LIMIT` применяется отдельно к каждому подключению.

- `TC1C_RECORD_MODE` — режим записи сценариев: `synth` (по умолчанию — сервер собирает сценарий из
  вызовов инструментов, покрывая все действия агента) или `native` (журнал самого тест-клиента).
- `TC_PLATFORM_VERSION` — целевая версия платформы (напр. `8.3.24.1548`): действия, чей метод в
  этой версии отсутствует, не публикуются; версия используется в рукопожатии.
- `TC1C_RESPONSE_FORMAT` — формат ответов: `toon` (по умолчанию) или `json` (режим совместимости).
- `TC1C_COMPACT_REFS` — адресация элементов: `id` (по умолчанию), `prefix` или `off`.
  `id` работает с TOON и JSON; `prefix` сокращает адреса только в TOON.
  Прежние `true` и `false` принимаются как синонимы `prefix` и `off`.
- `TC1C_REF_LIMIT` — максимум элементов в реестре одного подключения, по умолчанию `100000`;
  положительное целое число. Ограничение действует во всех режимах адресации.
- `TC1C_VERIFY_TARGET` — проверка существования объекта перед действием, `true` (по умолчанию)
  или `false`.
- `TC1C_READBACK` — чтение состояния до и после действия, `true` (по умолчанию) или `false`.

## Формат ответов

Формат ответов — **TOON** (компактный, по умолчанию) или **JSON**.
Выбор: `TC1C_RESPONSE_FORMAT`.

Режим адресации элементов задаётся через `TC1C_COMPACT_REFS`:

- `id` — короткие ссылки `ref`, передаваемые в действия без изменений; по умолчанию.
- `prefix` — сокращённые адреса со словарями в ответе TOON; в JSON адреса полные.
- `off` — полные адреса `key` и `handle`.

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

Сервер публикует **10 инструментов** — по типам объектов клиента тестирования; операция выбирается
параметром `action`, всего 136 действий. Список действий с методами 1С, применимыми типами и
параметрами вынесен в отдельный документ:
**[docs/TOOLS.md](docs/TOOLS.md)**.

## Запись и воспроизведение сценариев

`tc_scenario(action="record_start")` → выполнить действия → `tc_scenario(action="record_finish")` возвращает
XML-сценарий (`uilog`) и `lost_actions` (действия, не попавшие в сценарий; при непустом списке
сценарий неполный). Воспроизведение — `tc_scenario(action="run_scenario", uilog=...)`.
Режим записи — `TC1C_RECORD_MODE`.

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

- Протокол закрытый и может отличаться между версиями платформы. Локальное подключение проверено
  на Windows с 8.3.27 и 8.5.1; удалённое — к Windows с 8.3.27
  и к Ubuntu с 8.3.27. Способ подключения выбирается автоматически по ответу тест-клиента.