MCP сервер для работы с OData 1C

MCP (Model Context Protocol) сервер на Python для интеграции с системой 1С через OData API. Предоставляет инструменты для работы с данными, метаданными и документами 1С с автоматическим сохранением в JSON файлы.

Возможности

• 📊 Получение метаданных - структура метаобъектов 1С с сохранением в JSON
• 🔍 Запросы к данным - получение данных из 1С с сохранением в JSON файлы
• 🗂️ Локальная работа - фильтрация и анализ JSON данных без обращения к 1С
• 📝 CRUD операции - создание, редактирование, удаление документов
• 🏪 Специальные документы - создание документов РТиУ с бизнес-правилами
• 🔐 Аутентификация - Basic Auth для подключения к 1С
• 💾 JSON архитектура - все данные сохраняются в структурированные JSON файлы
• 📋 Логирование - структурированные логи через loguru

Особенности JSON-архитектуры

• Экономия контекста LLM - функции возвращают только статусную информацию
• Быстрая локальная работа - анализ данных без повторных запросов к 1С
• Персистентность данных - все загруженные данные сохраняются между сессиями
• Прозрачность - все данные доступны в читаемом JSON формате

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

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

uv sync

2. Конфигурация

Скопируйте config.example в .env и укажите параметры подключения:

cp config.example .env

Отредактируйте .env:

ODATA_BASE_URL=http://your-1c-server/Base/odata/standard.odata/
ODATA_USERNAME=your_username
ODATA_PASSWORD=your_password

3. Запуск сервера

uv run main.py

4. Подключение к серверу

"connect_1c_mcp": {
      "url": "http://localhost:8000/sse", // url сервера
      "transport": "sse"
},

Доступные инструменты

Получение данных из 1С

• fetch_1c_metadata() - получить и сохранить структуру метаобъектов в JSON
• fetch_1c_data() - получить данные из 1С и сохранить в JSON файл
• get_1c_entity() - получить конкретную сущность по ключу

CRUD операции с сущностями

• create_1c_entity() - создать новую сущность (справочник, документ и др.)
• update_1c_entity() - обновить существующую сущность в 1С
• delete_1c_document() - удалить документ из 1С
• create_rtu_document() - создать документ РТиУ на основании другого документа

Устаревшие функции (используйте новые)

• create_1c_document() → используйте create_1c_entity()
• update_1c_document() → используйте update_1c_entity()

Работа с локальными JSON данными

• list_cached_data() - получить список всех сохраненных JSON файлов
• get_file_structure() - получить структуру JSON файла (поля, типы, примеры)
• filter_local_data() - фильтровать и сортировать данные из локального JSON файла
• count_local_data() - подсчитать записи в локальном JSON файле

Управление кэшем

• get_cache_info() - получить информацию о состоянии кэша
• clear_metadata_cache() - очистить кэш метаданных
• clear_data_cache() - очистить все сохраненные данные

Рекомендуемый рабочий процесс

1. fetch_1c_metadata() - получить структуру метаобъектов 1С
2. fetch_1c_data() - загрузить нужные данные в JSON файл
3. list_cached_data() - посмотреть список сохраненных файлов
4. get_file_structure() - изучить структуру файла с данными
5. filter_local_data() с сортировкой или count_local_data() - анализировать локальные данные

Новые возможности локального анализа

Сортировка данных

# Получить первые 10 записей, отсортированных по полю "Description"
filter_local_data(
    file_name="Catalog_Products_abc123.json",
    sort_by="Description",
    sort_desc=False,  # По возрастанию
    limit=10
)

Анализ структуры файла

# Получить информацию о полях, типах и примерах значений
get_file_structure(file_name="Catalog_Products_abc123.json")

# Можно использовать короткое имя - система найдет файл автоматически
get_file_structure(file_name="Catalog_Products")

Создание и обновление сущностей

Создание элемента справочника

create_1c_entity(
    entity_set="Catalog_Products",
    data={
        "Code": "PROD001", 
        "Description": "Новый товар",
        "Price": 1000.00
    }
)

Создание документа

create_1c_entity(
    entity_set="Document_SalesOrder",
    data={
        "Number": "SO-001",
        "Organization_Key": "guid'...'",
        "Counterparty_Key": "guid'...'"
        # Дата будет добавлена автоматически
    }
)

Обновление сущности

update_1c_entity(
    entity_set="Catalog_Products",
    entity_key="guid'...'",
    data={
        "Description": "Обновленное наименование",
        "Price": 1200.00
    }
)

Умный поиск файлов

Все функции работы с локальными данными поддерживают умный поиск файлов:

Варианты поиска:

• По точному имени: Catalog_Products_abc123.json
• С расширением .json: Catalog_Products.json (найдет Catalog_Products_abc123.json)
• По началу имени: Catalog_Products (найдет Catalog_Products_abc123.json)
• По частичному совпадению: Products (найдет файл, содержащий "Products" в имени)

Правила поиска:

1. Сначала ищется точное совпадение имени файла
2. Если не найдено и запрос содержит .json, расширение убирается из поиска
3. Ищутся файлы, начинающиеся с указанного имени
4. Если не найдено, ищутся файлы, содержащие указанное имя
5. При множественных совпадениях выбирается самый новый файл

Архитектура

Подробное описание архитектуры проекта см. в architecture.md.

Требования

• Python 3.12+
• Доступ к OData API 1С
• Настроенная аутентификация в 1С

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

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