1C_MCP_SERVER_OWN

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

Источник разработки: 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 минуты)

# 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 режим (для локальных клиентов)

# Настройте переменные окружения
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 режим (для веб-клиентов)

# Создайте файл конфигурации
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

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

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

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

📋 API Методы

🔍 list_metadata_objects

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

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

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

📋 get_metadata_structure

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

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

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

🎯 list_predefined_data

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

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

📄 get_predefined_data

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

{
  "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 настройки

# Включить 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
│  (расширение)      │
└────────────────────┘

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

# Запуск автоматических тестов
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 - полная техническая документация
• ⚙️ env.example - пример конфигурации
• 🧪 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
• 💬 Discussions: GitHub Discussions
• 📧 Email: AlexMiaWat@gmail.com

---

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

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

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