# 1C MCP Gateway: подключение

## Локальный stdio transport для Cursor

```json
{
  "mcpServers": {
    "1c-mcp-gateway": {
      "command": "npm",
      "args": ["run", "dev:gateway"],
      "cwd": "/var/www/mwi.yatsuk.pro"
    }
  }
}
```

## Web Console и hosted/team HTTP

```bash
npm run dev:http
```

- Web Console: `http://localhost:3000`
- Streamable HTTP MCP endpoint: `http://localhost:3000/mcp`
- По умолчанию HTTP bind: `127.0.0.1`. Для другого интерфейса задайте `ONEC_MCP_HTTP_HOST`.
- `/mcp` принимает только persistent HTTP MCP tokens.

```bash
ONEC_MCP_HTTP_TOKEN="change-me" npm run dev:http
```

Если `ONEC_MCP_HTTP_TOKEN` задан, он импортируется в `.data/http-mcp-tokens.json` как `env-bootstrap`: в файле хранится только SHA-256 hash, сам secret не записывается.

Для hosted/team режима выпускайте отдельные токены через Web Console или API:

```http
POST /api/mcp-tokens
Content-Type: application/json

{
  "title": "Cursor team token",
  "scopes": ["mcp:call", "connections.manage:read", "usage-metering:read"],
  "expiresAt": "2026-12-31T23:59:59.000Z",
  "allowedClients": ["cursor"],
  "rateLimit": { "windowSeconds": 60, "maxRequests": 120 }
}
```

HTTP MCP clients must send:

```http
Authorization: Bearer <issued-http-mcp-token>
X-MCP-Client-ID: cursor
```

## Основной порядок работы AI-агента

1. `list_profiles`
2. `switch_active_profile`
3. `discover_1c_context`
4. `bsl_get_context_for_task`
5. `bsl_get_module` / `bsl_get_symbol` / `form_get_context`
6. `bsl_run_diagnostics` или `analyze_1c_error`

Production профили доступны только для read-only операций. Изменения кода и Agent Result Loop относятся к dev/test.

## Long operations: progress и cancellation

См. [LONG_OPERATIONS.md](LONG_OPERATIONS.md).

- `operation.list` — in-flight index jobs и Agent Result Loop
- `operation.cancel` — отмена по `operationId`
- Index tools возвращают `operationId` в JSON-ответе
- MCP `notifications/progress` при наличии `progressToken` в `_meta`

## EDT/Designer CLI для Beta/dev workflow

Внешние CLI-команды запускаются только через allowlist и только без shell.

```bash
export ONEC_CLI_ALLOWED_EXECUTABLES="/opt/1cv8/x86_64/8.3.24.1234/1cv8:/opt/1cedt/1cedtcli"
export ONEC_DESIGNER_EXECUTABLE="/opt/1cv8/x86_64/8.3.24.1234/1cv8"
export ONEC_EDT_EXECUTABLE="/opt/1cedt/1cedtcli"
export ONEC_DESIGNER_TIMEOUT_MS="600000"
export ONEC_EDT_TIMEOUT_MS="600000"
```

Важно:

- tools `run_edt_validation`, `export_1c_configuration`, `import_1c_configuration_to_test`, `build_1c_extension`, `load_extension_to_test_base` требуют `confirmed`, `businessReason`, `approvalId`, `idempotencyKey`;
- import/load дополнительно требуют `changeSummary` и `rollbackPlan`;
- `dryRun: true` возвращает preflight без запуска внешнего процесса;
- разрешены только `dev/test` профили;
- импорт и загрузка в базу разрешены только для `test`;
- пути должны быть относительными к `edtExportPath` или `gitPath` профиля;
- caller не передаёт raw executable или raw args: сервер сам выбирает `designer`/`edt` executable из env;
- production write/admin операции запрещены.

## Agent Result Loop через web-клиент

Браузерные tools работают только для `dev/test` профилей с `baseUrl` опубликованного web-клиента 1С.

```bash
export ONEC_WEB_CLIENT_BROWSER_EXECUTABLE="/usr/bin/chromium"
export ONEC_WEB_CLIENT_BROWSER_ALLOWED_EXECUTABLES="/usr/bin/chromium"
export ONEC_FEEDBACK_HEADLESS="1"
export ONEC_FEEDBACK_NAVIGATION_TIMEOUT_MS="30000"
```

Tools:

- `open_1c_client`
- `open_1c_form`
- `get_1c_form_screenshot`
- `run_1c_ui_smoke_test`
- `restart_1c_session`

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

- URL должен оставаться внутри origin `profile.baseUrl`;
- HTTPS обязателен, если не задан `ONEC_FEEDBACK_ALLOW_HTTP=1`;
- если задан внешний browser executable, он должен быть absolute и входить в `ONEC_WEB_CLIENT_BROWSER_ALLOWED_EXECUTABLES`;
- smoke checks принимают `requiredText` и `buttons`, произвольные CSS selectors/JS не принимаются;
- screenshots сохраняются в `.data/screenshots/{profileId}/{artifactId}` и возвращают sha256/size;
- thin/thick 1C client automation не входит в этот web feedback контур.

## End-to-end Agent Result Loop

Оркестратор не генерирует код сам и не выполняет скрытых действий. Он связывает уже подтверждённые шаги:

1. `approval.create` для `run_agent_result_loop`
2. `create_agent_result_loop`
3. `run_agent_result_loop`
4. `get_agent_result_loop_status`

`run_agent_result_loop` может выполнить только явно переданные этапы:

- apply ранее созданного `proposalId`;
- `run_bsl_checks`;
- `run_edt_validation`;
- `build_1c_extension`;
- `load_extension_to_test_base`;
- `open_1c_form`;
- `get_1c_form_screenshot`;
- `run_1c_ui_smoke_test`.

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

- только `dev/test`;
- load extension/configuration только для `test`;
- обязательны `confirmed`, `businessReason`, `changeSummary`, `rollbackPlan`, `approvalId`, `idempotencyKey`;
- статус каждого шага сохраняется в `.data/agent-result-loops.json`;
- при ошибке шаг помечается `failed`, дальнейший сценарий останавливается.

## Approvals

Write/feedback действия требуют persistent one-time approval:

```text
approval.create -> approvalId -> write/feedback tool
```

Approval привязан к:

- `profileId`;
- `toolName`;
- `actor`;
- `businessReason`;
- сроку действия.

Для создания нового профиля, когда `profileId` ещё не существует, создавайте approval с `profileId: "new"` или без `profileId`, но с `environment`.

После использования approval получает статус `used`; повторное применение запрещено. Событие использования пишется в append-only audit log `.data/audit.jsonl`.

## Audit redaction

Перед записью в `.data/audit.jsonl` события проходят централизованную маскировку:

- ключи с секретами: `authorization`, `password`, `secret`, `apiKey`, `cookie`, `session`, `credential`, `accessToken`, `refreshToken`;
- большие документы и raw payload: `oldText`, `newText`, `content`, `document`, `body`, `diff`, `stdout`, `stderr`, `rows`, `html`;
- PII-поля: `email`, `phone`, `passport`, `snils`, `inn`, `username`, `fullName`, `birthDate`, `address`;
- строки с `Bearer ...`, `Basic ...`, email и URL credentials.

Безопасные идентификаторы вроде `tokenId`, `tokenPrefix`, `tokenEnv`, `passwordEnv`, `idempotencyKey` сохраняются, потому что это не значения секретов.

## Identity model

Web Console ведёт persistent identity store `.data/identity.json`.

Поддерживаются principal types:

- `web-console-user`;
- `mcp-caller`;
- `service-account`;
- `onec-user`.

HTTP MCP token может быть привязан к:

- `actorPrincipalId` — кто вызывает MCP;
- `onBehalfOfPrincipalId` — от чьего имени выполняется действие;
- `oneCUsername` — связанный пользователь 1С для профиля/сценария.

Mappings principal -> 1C user сохраняются через `/api/identity/onec-mappings`. Эти поля попадают в audit только как идентификаторы; PII-поля маскируются redaction слоем.