# Быстрый старт

Минимальный путь от установки до первого успешного MCP tool call с контекстом 1С.

## Prerequisites

- Node.js 22+ и npm.
- Клон репозитория: `/var/www/mwi.yatsuk.pro`.
- Одна из баз: опубликованная 1С (OData), файловая ИБ (dev/test) или выгрузка EDT/Git.
- Cursor или другой MCP-клиент с поддержкой stdio.

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

### 1. Установка зависимостей

```bash
cd /var/www/mwi.yatsuk.pro
npm ci
npm run typecheck
npm run build
```

### 2. Каталог данных

По умолчанию gateway пишет в `.data`. Для отдельного тома:

```bash
export ONEC_MCP_DATA_DIR=/var/lib/onec-mcp-gateway
mkdir -p "$ONEC_MCP_DATA_DIR"
```

### 3. Запуск stdio gateway (локальная IDE)

```bash
npm run dev:gateway
```

Gateway стартует как MCP-сервер на stdin/stdout. Actor по умолчанию: `local-ai-agent`.

### 4. Подключение Cursor

Скопируйте конфиг в `~/.cursor/mcp.json` (или Project MCP settings):

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

Перезапустите Cursor и включите сервер `1c-mcp-gateway`.

### 5. Создание профиля через Web Console (опционально)

Для управления подключениями удобнее HTTP-режим:

```bash
ONEC_MCP_HTTP_TOKEN="dev-bootstrap-token" npm run dev:http
```

- Web Console: `http://localhost:3000`
- Создайте Organization → Project → Connection (тип `edt-export` или `published-web`).
- Установите профиль активным через Active Base Switcher.

### 6. Проверка health

В IDE вызовите tool `check_profile_health` с `profileId` созданного профиля или `list_profiles` для списка.

## Copy-ready config (HTTP team mode)

```bash
export ONEC_MCP_HTTP_HOST=127.0.0.1
export ONEC_MCP_HTTP_PORT=3000
export ONEC_MCP_HTTP_TOKEN="change-me-before-prod"
export ONEC_MCP_ACTOR=web-console
npm run dev:http
```

MCP endpoint: `http://localhost:3000/mcp`  
Headers: `Authorization: Bearer <token>`, `X-MCP-Client-ID: cursor`

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

В Cursor откройте MCP panel → `1c-mcp-gateway` → Tools. Должны быть видны минимум:

- `list_profiles`, `get_active_profile`, `switch_active_profile`
- `discover_1c_context`, `bsl_search`, `bsl_get_context_for_task`
- `check_profile_health`, `check_connection_health`

Если список пуст — проверьте, что `npm run dev:gateway` запущен и путь `cwd` корректен.

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

```
Вызови list_profiles, переключись на активный dev-профиль через switch_active_profile,
затем discover_1c_context по объекту «Справочник.Контрагенты» и верни краткую сводку
связанных модулей и форм.
```

Ожидаемый результат: структурированный JSON с модулями, формами и обработчиками без секретов и connection string.

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

| Симптом | Причина | Решение |
|---------|---------|---------|
| MCP server disconnected | Неверный `cwd` или Node не в PATH | Укажите абсолютный путь в config |
| `profile not found` | Профиль не создан | Web Console или tool `connect_*` |
| `HTTPS required` | HTTP baseUrl в prod | Используйте HTTPS или `ONEC_MCP_ALLOW_INSECURE_HTTP=1` только в dev |
| Tools не появляются | Старый кэш Cursor | Reload Window, переподключите MCP |

## Security warning

- Не используйте production-базы в write-режиме на этапе быстрого старта.
- `ONEC_MCP_HTTP_TOKEN` — только для dev; в prod выпускайте scoped tokens через `/api/mcp-tokens`.
- Секреты (`passwordEnv`, `tokenEnv`) храните в env, не в профиле JSON и не в промптах AI.

## Related docs

- [MCP_CONNECTION.md](./MCP_CONNECTION.md) — transport, токены, agent workflow
- [ONEC_ODATA_SETUP.md](./ONEC_ODATA_SETUP.md) — публикация OData
- [EDT_DESIGNER_EXPORT.md](./EDT_DESIGNER_EXPORT.md) — offline BSL context
- [TROUBLESHOOTING.md](./TROUBLESHOOTING.md) — расширенная диагностика