# Подготовка 1С: HTTP-сервис и расширение

Настройка HTTP-сервиса gateway в 1С для health check, typed business operations и расширенной интеграции.

## Prerequisites

- Опубликованная 1С-база с HTTPS.
- Возможность установить расширение или добавить HTTP-сервис в конфигурацию.
- Путь по умолчанию gateway: `/hs/mcp-gateway/` (настраивается в профиле).
- Для business ops — каталог операций с `operationId`, method, path, allowedEnvironments.

## Пошаговая настройка

### 1. Структура HTTP-сервиса в 1С

Минимальный контракт для health:

```
GET /hs/mcp-gateway/health → 200 OK, JSON { "status": "ok" }
```

Рекомендуемые URL-шаблоны (расширение):

- `GET  .../health` — проверка доступности
- `GET  .../operations` — каталог typed operations (опционально)
- `POST .../operations/{operationId}` — выполнение с JSON body

### 2. Публикация на веб-сервере

1. Администрирование → Публикация → добавьте HTTP-сервис `mcp-gateway`.
2. Корень публикации должен совпадать с `baseUrl` профиля.
3. Проверьте:

```bash
curl -sS -H "Authorization: Bearer $ONEC_HTTP_TOKEN" \
  "https://your-1c-host/your-base/hs/mcp-gateway/health"
```

### 3. Профиль gateway

```json
{
  "profileId": "team-http",
  "type": "published-web",
  "environment": "test",
  "baseUrl": "https://your-1c-host/your-base",
  "httpServicePath": "/hs/mcp-gateway/",
  "auth": {
    "mode": "bearer",
    "tokenEnv": "ONEC_HTTP_SERVICE_TOKEN"
  }
}
```

### 4. Строгий режим (production)

```bash
export ONEC_MCP_REQUIRE_HTTP_SERVICE_PATH=1
```

Без `httpServicePath` профиль не пройдёт health check.

### 5. Регистрация business operations

Каталог хранится в `.data/business-operations.json` (per profileId). Пример записи:

```json
{
  "operationId": "get_customer_balance",
  "httpMethod": "POST",
  "path": "operations/get_customer_balance",
  "allowedEnvironments": ["test"],
  "riskLevel": "business-read",
  "requiredScopes": ["runtime.actions"]
}
```

Runtime tool `execute_1c_business_operation` доступен только при явном включении policy (не MVP read-only).

## Copy-ready config

```bash
export ONEC_HTTP_SERVICE_TOKEN="service-token-from-vault"
export ONEC_MCP_REQUIRE_HTTP_SERVICE_PATH=1
export ONEC_MCP_DATA_DIR=.data
npm run dev:http
```

Создание scoped MCP token для HTTP transport:

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

{
  "title": "HTTP service reader",
  "scopes": ["mcp:call", "connections.manage:read"],
  "allowedClients": ["cursor"]
}
```

## Проверка tools/list

- `check_connection_health` — всегда для `published-web`
- `execute_1c_business_operation` — только если scope `runtime.actions` и env `test`/`dev`
- Write/admin tools требуют approval (см. [MCP_CONNECTION.md](./MCP_CONNECTION.md))

Вызовите `check_connection_health` — поле HTTP service должно быть `ok: true`.

## Первый тестовый prompt

```
Для профиля team-http вызови check_connection_health и покажи статус HTTP-сервиса.
Если доступен dryRun, выполни execute_1c_business_operation с operationId из каталога
и dryRun: true — покажи preview URL и method без реального вызова.
```

## Типовые ошибки

| Ошибка | Причина | Решение |
|--------|---------|---------|
| `404` на `/health` | Сервис не опубликован | Проверьте публикацию и `httpServicePath` |
| `profile.httpServicePath is required` | Strict mode | Задайте path или снимите `ONEC_MCP_REQUIRE_HTTP_SERVICE_PATH` |
| `Operation not allowed in production` | Env mismatch | Операция только для test/dev |
| Timeout 10s | Медленный кластер 1С | Увеличьте ресурсы ИБ, проверьте сеть |
| 401 на bearer | Неверный `tokenEnv` | Обновите secret, не логируйте token |

## Security warning

- HTTP-сервис — потенциальный write-канал: каждая операция должна быть typed, с idempotency и audit.
- Не реализуйте универсальный `execute_code` или произвольный вызов методов 1С.
- Production: только read-only health + явно одобренный каталог operations с `dryRun` preview.
- Секреты — через `tokenEnv` / vault (`ONEC_VAULT_ADDR`), never in tool args.

## Related docs

- [ONEC_ODATA_SETUP.md](./ONEC_ODATA_SETUP.md) — параллельный read-only канал
- [MCP_CONNECTION.md](./MCP_CONNECTION.md) — approvals, Agent Result Loop
- [SECURITY_MODEL.md](./SECURITY_MODEL.md) — risk levels, scopes
- [THREAT_MODEL.md](./THREAT_MODEL.md) — abuse HTTP endpoint