Content
# 1C Testpilot
MCP-сервер для работы AI-агентов с интерфейсом **1С:Предприятия**. Позволяет агенту
открывать формы, читать и изменять данные, работать с таблицами, записывать и воспроизводить
сценарии действий.
Сервер подключается напрямую к локальному или удалённому клиенту тестирования 1С
по его сетевому протоколу.
## Возможности
- Подключение к локальному или удалённому тест-клиенту по адресу и порту; порядок подключения
определяется автоматически.
- Запуск/останов тест-клиента 1С на компьютере MCP-сервера (файловая или серверная база, логин/пароль) с ожиданием
готовности и авто-подключением — `tc_session(action="launch_client"/"stop_client")`.
- Навигация по дереву UI: активное окно → форма → элементы (по иерархическим ключам).
- Чтение: значения полей, вид/класс/заголовки элементов, таблицы, области табличного документа.
- Действия: ввод текста/HTML, клики, флажки, выбор из списков/меню, работа с таблицами и деревом,
календарь, гиперссылки, навигация по строкам и окнам.
- **Запись и воспроизведение сценариев** (uilog): агент выполняет шаги → получает XML-сценарий →
воспроизводит его. Два режима записи (см. [переменные окружения](#переменные-окружения)).
- 10 инструментов по типам объектов клиента тестирования; конкретная операция выбирается
параметром `action` (137 действий). Версионный гейтинг по целевой версии платформы.
## Требования
- 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`, всего 137 действий. Список действий с методами 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. Способ подключения выбирается автоматически по ответу тест-клиента.
Connection Info
You Might Also Like
No recommendations available