# 1C_MCP_SERVER_OWN
Доработка и адаптация MCP 1С под текущие задачи при работе с Агентами

[![Python](https://img.shields.io/badge/Python-3.11+-blue.svg)](https://www.python.org/)
[![1C](https://img.shields.io/badge/1C-Enterprise-orange.svg)](https://1c.ru/)
[![MCP](https://img.shields.io/badge/MCP-Protocol-green.svg)](https://modelcontextprotocol.io/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**Источник разработки:** https://github.com/vladimir-kharin/1c_mcp

> **MCP-прокси сервер для 1С:Предприятие** - мост между AI-агентами (Claude, Cursor) и вашей базой 1С. Получайте метаданные, анализируйте структуру конфигурации и генерируйте код через естественный язык!

## ✨ Что это такое

Представьте, что у вас есть мощный ИИ-помощник, который может "разговаривать" с вашей базой 1С. Этот прокси-сервер как переводчик: он берет запросы от ИИ на понятном ему языке (MCP-протокол) и переводит их в команды, которые понимает 1С.

**Простыми словами:**
- 🤖 ИИ спрашивает: "Какие справочники есть в конфигурации?"
- 🔄 Прокси переводит это в JSON-RPC запрос к 1С
- 📊 1С отвечает списком справочников
- ✅ Прокси переводит ответ обратно для ИИ

## 🎯 Ключевые возможности

- **🔄 Два режима работы:** stdio (для локальных программ) и HTTP (для веб-приложений)
- **🔐 Безопасность:** OAuth2 авторизация - каждый пользователь работает под своими учетными данными
- **⚡ Быстродействие:** асинхронная обработка, поддержка множества одновременных пользователей
- **🔧 Универсальность:** работает со всеми типами MCP-клиентов
- **📊 Аналитика:** получение метаданных, структуры объектов, предопределенных данных

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

### ⚡ Установка (2 минуты)

```bash
# 1. Клонируйте репозиторий
git clone https://github.com/your-repo/1c-mcp-server.git
cd 1c-mcp-server

# 2. Создайте виртуальное окружение
python -m venv venv

# 3. Активируйте окружение
venv\Scripts\activate  # Windows
source venv/bin/activate  # Linux/Mac

# 4. Установите зависимости
pip install -r requirements.txt
```

### 🚀 Первый запуск

#### Вариант A: Stdio режим (для локальных клиентов)

```bash
# Настройте переменные окружения
set MCP_ONEC_URL=http://localhost/base
set MCP_ONEC_USERNAME=admin
set MCP_ONEC_PASSWORD=password

# Запустите сервер
python -m src.py_server stdio
```

#### Вариант B: HTTP режим (для веб-клиентов)

```bash
# Создайте файл конфигурации
copy env.example .env

# Отредактируйте .env (минимум):
# MCP_ONEC_URL=http://localhost/base
# MCP_ONEC_USERNAME=admin
# MCP_ONEC_PASSWORD=password

# Запустите сервер
python -m src.py_server http --port 8000
```

### ✅ Проверка работы

```bash
# Проверьте здоровье сервера
curl http://localhost:8000/health

# Ожидаемый ответ:
{
  "status": "healthy",
  "onec_connection": "ok",
  "auth": {"mode": "none"}
}
```

## 📋 API Методы

### 🔍 list_metadata_objects
Получить список объектов метаданных указанного типа.

```json
{
  "name": "list_metadata_objects",
  "arguments": {
    "metaType": "Catalogs",
    "nameMask": "Номенклатура",
    "maxItems": 10
  }
}
```

**Результат:** Список найденных объектов с именами и описаниями.

### 📋 get_metadata_structure
Получить подробную структуру объекта (реквизиты, табличные части).

```json
{
  "name": "get_metadata_structure",
  "arguments": {
    "metaType": "Catalogs",
    "name": "Номенклатура"
  }
}
```

**Результат:** Полная структура объекта с типами данных.

### 🎯 list_predefined_data
Получить список предопределенных элементов.

```json
{
  "name": "list_predefined_data",
  "arguments": {
    "metaType": "Catalogs",
    "name": "Номенклатура",
    "predefinedMask": "Услуга"
  }
}
```

### 📄 get_predefined_data
Получить детальную информацию о предопределенном элементе.

```json
{
  "name": "get_predefined_data",
  "arguments": {
    "metaType": "Catalogs",
    "name": "Номенклатура",
    "predefinedName": "Услуга"
  }
}
```

## ⚙️ Конфигурация

### Основные параметры

| Параметр | Описание | По умолчанию | Обязательный |
|----------|----------|--------------|--------------|
| `MCP_ONEC_URL` | URL базы 1С | - | ✅ |
| `MCP_ONEC_USERNAME` | Имя пользователя | - | ✅ (без OAuth2) |
| `MCP_ONEC_PASSWORD` | Пароль | - | ✅ (без OAuth2) |
| `MCP_HOST` | Хост сервера | `127.0.0.1` | ❌ |
| `MCP_PORT` | Порт сервера | `8000` | ❌ |
| `MCP_AUTH_MODE` | Режим авторизации | `none` | ❌ |

### OAuth2 настройки

```bash
# Включить OAuth2
MCP_AUTH_MODE=oauth2
MCP_PUBLIC_URL=http://your-server:8000

# Таймауты токенов
MCP_OAUTH2_CODE_TTL=120      # authorization code (сек)
MCP_OAUTH2_ACCESS_TTL=3600   # access token (сек)
MCP_OAUTH2_REFRESH_TTL=1209600  # refresh token (14 дней)
```

## 🔧 Режимы работы

### Stdio режим
- 💻 Для локальных MCP-клиентов (Claude Desktop, Cursor)
- 📡 Общение через stdin/stdout
- 🔒 Логи идут в stderr

### HTTP режим
- 🌐 Для веб-приложений и множественных клиентов
- 📊 Endpoints: `/mcp/`, `/sse`, `/health`, `/info`
- 🔐 Поддержка OAuth2 авторизации

## 🔐 Авторизация

### Без OAuth2 (по умолчанию)
Все запросы выполняются от одного пользователя из конфигурации.

### С OAuth2
Каждый клиент авторизуется своими креденшилами 1С.

**Поддерживаемые flows:**
- 🔑 **Password Grant** - прямая передача username/password
- 🔄 **Authorization Code + PKCE** - стандартный flow с формой авторизации

## 🏗️ Архитектура

```
┌─────────────────┐
│   MCP Client    │  🤖 Claude Desktop, Cursor
│  (stdio/HTTP)   │
└────────┬────────┘
         │ MCP Protocol
         ▼
┌────────────────────┐
│  Python Proxy      │  🔄 Проксирование MCP → JSON-RPC
│  - mcp_server      │
│  - http_server     │
│  - stdio_server    │
│  - onec_client      │
└────────┬───────────┘
         │ JSON-RPC over HTTP
         │ 🔐 Basic Auth (username:password)
         ▼
┌────────────────────┐
│  1C HTTP Service   │  📡 /hs/mcp/rpc
│  (расширение)      │
└────────────────────┘
```

## 🧪 Тестирование

```bash
# Запуск автоматических тестов
python testMCP_grok_plus_2.py

# Результаты сохраняются в testMCP.md
```

## ❓ Устранение неполадок

### 🔌 "Не удается подключиться к 1С"
1. Проверьте `MCP_ONEC_URL`
2. Убедитесь, что HTTP-сервис 1С опубликован
3. Проверьте учетные данные
4. Включите DEBUG логи: `--log-level DEBUG`

### 🔐 "OAuth2 авторизация не работает"
1. Установите `MCP_AUTH_MODE=oauth2`
2. Проверьте `MCP_PUBLIC_URL`
3. Для Password Grant: проверьте креденшилы
4. Для Authorization Code: проверьте PKCE параметры

### 🛠️ "MCP-клиент не видит инструменты"
1. Проверьте конфигурацию клиента
2. Убедитесь, что сервер запущен
3. Проверьте логи на ошибки
4. Для stdio: проверьте переменные окружения

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

- 📖 **[agents.md](agents.md)** - полная техническая документация
- ⚙️ **[env.example](env.example)** - пример конфигурации
- 🧪 **[testMCP.md](testMCP.md)** - результаты тестирования

## 🤝 Contributing

Мы приветствуем вклад в развитие проекта!

1. 🍴 Fork репозиторий
2. 🌿 Создайте feature branch: `git checkout -b feature/amazing-feature`
3. 💾 Commit изменения: `git commit -m 'Add amazing feature'`
4. 📤 Push в branch: `git push origin feature/amazing-feature`
5. 🔄 Создайте Pull Request

## 📄 Лицензия

**MIT License** - свободно используйте в коммерческих и личных проектах.

## 📞 Контакты

- 🐛 **Issues:** [GitHub Issues](https://github.com/AlexMiaWat/1C_MCP_SERVER_OWN/issues)
- 💬 **Discussions:** [GitHub Discussions](https://github.com/AlexMiaWat/1C_MCP_SERVER_OWN/discussions)
- 📧 **Email:** AlexMiaWat@gmail.com

---

**Источник разработки:** https://github.com/vladimir-kharin/1c_mcp

⭐ **Если проект оказался полезным, поставьте звезду на GitHub!**

*Разработано с ❤️ для сообщества 1С разработчиков*
