iflow-mcp_vladimir-kharin-1c_mcp 1.0.0
MCP-proxy server for 1C:Enterprise integration
Requires Python: >=3.11

# Разработка MCP-серверов в 1С

Инструмент для создания MCP (Model Context Protocol) серверов на платформе 1С:Предприятие. Позволяет разрабатывать расширения 1С, которые предоставляют данные и функциональность базы для AI-ассистентов (чаты с языковыми моделями, Claude Desktop, Cursor и других AI-клиентов).

Подробное видео о проекте и его возможностях:  
[VK Видео](https://vkvideo.ru/video-219359576_456239024) | [Youtube](https://youtu.be/ZEla85JsfCo) | [Rutube](https://rutube.ru/video/ba1c64432d1a5b6cfd2335b83bf47071/)

Проект содержит готовое расширение для 1С, которое берет на себя всю техническую рутину протокола MCP. Вам остается только реализовать бизнес-логику ваших инструментов. Инструменты для работы с метаданными конфигурации 1С доступны "из коробки".

## Как это работает: Концепция MCP

Качество ответа языковой модели (LLM) напрямую зависит от качества предоставленного ей контекста. Подготовка такого контекста вручную может быть трудоемкой.

**Model Context Protocol (MCP)** — это открытый стандарт, который позволяет модели самой запрашивать необходимые данные через специальные "инструменты" (tools), предоставляемые вашим сервером. Таким образом, контекст для решения задачи собирается автоматически.

## Компоненты проекта

1.  **`src/1c_ext/`** - **Расширение 1С:** Ядро решения. Реализует MCP-сервер и инструменты.
2.  **`src/py_server/`** - **Python-прокси:** Опциональный, но рекомендуемый компонент для решения инфраструктурных задач.

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

### Шаг 1: Установка расширения 1С

Подключите готовое, собранное расширение из каталога `build/MCP_Сервер.cfe` в вашу конфигурацию.

### Шаг 2: Публикация HTTP-сервиса

Опубликуйте на веб-сервере HTTP-сервис `mcp_APIBackend`, который находится в расширении.

> **Важно:** Для прямого подключения AI-клиента к 1С (без прокси) требуется публиковать базу без необходимости аутентификации ("вшить" реквизиты доступа к базе в default.vrd), что является небезопасным. Решение этой проблемы описано в разделе "Варианты подключения".

### Шаг 3: Подключение AI-клиента

Подключите MCP-клиент (например, Cursor) к опубликованному HTTP-сервису (`.../ваша_база/hs/mcp/`). Примеры настроек для разных клиентов находятся в папке [`mcp_client_settings/`](./mcp_client_settings/).

## Варианты подключения

### Вариант 1: Прямое подключение к 1С

- **Как работает:** `AI-клиент ←→ HTTP-сервис 1С`
- **Ограничения:**
    - Требует публикации HTTP-сервиса без аутентификации 1С.
    - Невозможно подключить клиенты, требующие транспорт `stdio`.
    - Ограниченная совместимость с некоторыми HTTP-клиентами из-за нюансов протокола.

### Вариант 2: Подключение через Python-прокси (Рекомендуется)

- **Как работает:** `AI-клиент ←→ MCP-прокси (Python) ←→ HTTP-сервис 1С`
- **Зачем он нужен?** Прокси решает ключевые инфраструктурные проблемы:
    - **Проблема транспорта:** Позволяет подключать клиенты, работающие по `stdio`.
    - **Проблема аутентификации:** Реализует протокол `OAuth2` (стандартный способ аутентификации в MCP) и передает авторизацию в 1С через `Basic Auth`. Это позволяет **не отключать** аутентификацию 1С на веб-сервере. Прокси поддерживает два режима: работа от имени одного фиксированного пользователя или "проброс" аутентификации каждого пользователя под его собственными учетными данными.

- **Настройка и запуск прокси:**
    - Детальная инструкция по требованиям, установке, настройке и запуску находится в [документации Python-прокси](./src/py_server/README.md).

### Вариант 3: Запуск прокси в Docker

Для изолированного запуска прокси-сервера в контейнере:

```bash
# Скопируйте пример конфигурации
cp .env.docker.example .env

# Отредактируйте .env (укажите URL, логин, пароль)
# Запустите контейнер
docker-compose up -d
```

> **Важно:** Если 1С на том же хосте, используйте `host.docker.internal` вместо `localhost` в `MCP_ONEC_URL`.

Подробнее в [документации Python-прокси](./src/py_server/README.md#docker).

## Разработка собственных инструментов

Функциональность расширяется добавлением собственных инструментов для взаимодействия с данными 1С.

- **Шаг 1:** В расширении создайте новую обработку и включите ее в подсистему `mcp_КонтейнерыИнструментов`.

- **Шаг 2:** В модуле менеджера этой обработки реализуйте два экспортных метода:

```bsl
// Метод для описания инструментов и их параметров
Процедура ДобавитьИнструменты(Инструменты) Экспорт
	// ... здесь вы описываете, какие инструменты предоставляет ваша обработка
КонецПроцедуры

// Метод для выполнения логики инструмента
Функция ВыполнитьИнструмент(ИмяИнструмента, Аргументы) Экспорт
	// ... здесь вы реализуете логику, которая будет вызвана AI-моделью
КонецФункции
```

Подробное руководство по разработке находится в файле [`src/1c_ext/agents.md`](./src/1c_ext/agents.md).

## Другие примитивы MCP

Помимо **Инструментов (Tools)**, проект также поддерживает **Ресурсы (Resources)** для предоставления статического контекста (например, файлов) и **Промпты (Prompts)** для заготовленных шаблонов сообщений.

## Документация

- **[Документация Python-прокси](./src/py_server/README.md)** — детальное описание настройки и запуска прокси-сервера.
- **[Руководство по разработке в 1С](./src/1c_ext/agents.md)** — подробности реализации инструментов, ресурсов и промптов на стороне 1С. Можно подключать к генераторам кода (AI-агентам).
- **[Примеры настроек клиентов](./mcp_client_settings/)** — готовые конфигурации для разных AI-клиентов.

## Лицензия

MIT License

## Поддержка и развитие

Проект активно развивается. Вопросы и предложения по улучшению приветствуются через Issues.