# MCP Сервер для 1С та BAS ERP (bas-mcp-server)

Цей проєкт реалізує проміжний сервіс (MCP-сервер) на базі Node.js та TypeScript для підключення AI-агентів (таких як Claude Desktop, Cursor, VS Code) до систем **1С:Підприємство** та **BAS ERP** (Business Automation Software).

Сервер взаємодіє з 1С через вбудований REST API (OData) та кастомний HTTP-сервіс для складних операцій.

---

## Архітектура рішення

### Варіант А: stdio через SSH-тунель (однокористувацький режим)
```
[Локальний AI Клієнт] (Claude Desktop / Cursor)
       │
       │  (MCP Protocol через SSH-тунель stdio)
       ▼
[Middleware MCP Server] (Node.js на боці сервера 1С)
       │
       │  (REST API / OData / HTTP)
       ▼
[1С:Підприємство / BAS ERP]
```

### Варіант Б: SSE через HTTP/HTTPS (багатокористувацький режим)
```
[AI Клієнт Користувача 1] ───┐
                             ├───> [Middleware MCP Server] ───> [1С / BAS ERP]
[AI Клієнт Користувача 2] ───┘      (Порт 3000 / HTTP / SSE)
```

---

## Функціональність (MCP Tools)

Агент отримує доступ до наступних інструментів:
*   `search_catalog` — пошук контрагентів, товарів (номенклатури), складів тощо.
*   `get_catalog_element` — зчитування всіх реквізитів обраного елемента за його GUID.
*   `create_catalog_element` — створення нових контрагентів або інших елементів довідників.
*   `create_document` — створення документів (наприклад, Замовлення клієнта, Рахунок на оплату).
*   `post_document` — проведення створених документів у базі.
*   `get_stock_balance` — отримання актуальних залишків товарів на складах.

---

## Швидкий старт (Mock-режим для тестів)

Ви можете протестувати сервер та його інтеграцію з AI-клієнтом локально без реального підключення до бази 1С.

1.  Встановіть залежності:
    ```bash
    npm install
    ```
2.  Скомпілюйте TypeScript код:
    ```bash
    npm run build
    ```
3.  Налаштуйте конфіг для тестування (вже містить `ONEC_USE_MOCK=true` у `.env` файлі за замовчуванням):
    ```bash
    cp .env.example .env
    ```
4.  Запустіть та протестуйте MCP-сервер у режимі інспектора (буде запущено як SSE сервер):
    ```bash
    npm run inspector
    ```

---

## Налаштування підключення до реальної 1С / BAS

### Крок 1. Налаштування на боці 1С
1. **Увімкніть OData:**
   Для роботи довідників увімкніть стандартний REST-інтерфейс 1С. Це можна зробити кодом:
   ```bsl
   СистемаИмпортаЭкспортаМакетаДанных.УстановитьИспользованиеRESTИнтерфейса(Истина);
   ```
2. **Встановіть Розширення для HTTP-сервісу:**
   Для проведення документів та залишків додайте розширення конфігурації. Інструкція та готовий BSL-код знаходяться в докумені: [docs/onec_http_service.md](file:///Users/roman/Projects/my/MCP/bas-mcp/docs/onec_http_service.md).

### Крок 2. Конфігурація Middleware (`.env`)
Відредагуйте файл `.env`:
```ini
ONEC_URL=http://your-1c-server/base-name
ONEC_USER=McpAgent
ONEC_PASSWORD=agent-password
ONEC_USE_ODATA=true
ONEC_USE_MOCK=false

# Налаштування транспорту та безпеки
MCP_TRANSPORT=sse
PORT=3000
MCP_API_KEY=your-secure-mcp-token-here
```

---

## Підключення до AI Клієнтів

### Варіант 1: Через SSE / HTTP (Багатокористувацький режим)
Додайте наступний блок у конфіг Claude Desktop (`~/Library/Application Support/Claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "bas-mcp-sse": {
      "url": "http://your-server-ip:3000/sse?apiKey=your-secure-mcp-token-here"
    }
  }
}
```

### Варіант 2: Через SSH-тунель (Stdio — для одного розробника)
Якщо ви не хочете відкривати порти в інтернет, ви можете використовувати SSH-тунель. Для цього у `.env` вкажіть `MCP_TRANSPORT=stdio`.
Налаштуйте безпарольний доступ по SSH за допомогою ключів до вашого сервера (`ssh-copy-id user@your-server-ip`), а потім додайте конфіг у локальний Claude Desktop:

```json
{
  "mcpServers": {
    "bas-mcp-stdio": {
      "command": "ssh",
      "args": [
        "-T",
        "user@your-server-ip",
        "node /path/to/your/project/bas-mcp/build/index.js"
      ]
    }
  }
}
```
Клієнт автоматично запустить процес на сервері через SSH та буде спілкуватися з ним за допомогою стандартних потоків (`stdio`).