mcp-1c 0.1.0.1
MCP сервер для работы с 1С через протокол OData
Requires Python: >=3.12


# 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. Установка зависимостей

```bash
uv sync
```

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

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

```bash
cp config.example .env
```

Отредактируйте `.env`:
```env
ODATA_BASE_URL=http://your-1c-server/Base/odata/standard.odata/
ODATA_USERNAME=your_username
ODATA_PASSWORD=your_password
```

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

```bash
uv run main.py
```

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

```json
"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()` - анализировать локальные данные

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

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

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

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

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

#### Создание элемента справочника
```python
create_1c_entity(
    entity_set="Catalog_Products",
    data={
        "Code": "PROD001", 
        "Description": "Новый товар",
        "Price": 1000.00
    }
)
```

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

#### Обновление сущности
```python
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](architecture.md).

## Требования

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

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