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. Встановіть залежності:

   npm install
   

2. Скомпілюйте TypeScript код:

   npm run build
   

3. Налаштуйте конфіг для тестування (вже містить ONEC_USE_MOCK=true у .env файлі за замовчуванням):

   cp .env.example .env
   

4. Запустіть та протестуйте MCP-сервер у режимі інспектора (буде запущено як SSE сервер):

   npm run inspector
   

---

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

Крок 1. Налаштування на боці 1С

1. Увімкніть OData: Для роботи довідників увімкніть стандартний REST-інтерфейс 1С. Це можна зробити кодом:

   СистемаИмпортаЭкспортаМакетаДанных.УстановитьИспользование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:

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):

{
  "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:

{
  "mcpServers": {
    "bas-mcp-stdio": {
      "command": "ssh",
      "args": [
        "-T",
        "user@your-server-ip",
        "node /path/to/your/project/bas-mcp/build/index.js"
      ]
    }
  }
}

Клієнт автоматично запустить процес на сервері через SSH та буде спілкуватися з ним за допомогою стандартних потоків (stdio).