# MCP сервер для AI-ассистентов (справка по синтаксису и объектной модели 1С:Предприятие)

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

## Обзор

Приложение `mcp-bsl-context` предназначено исключительно для интеграции с AI-ассистентами, чтобы они могли выполнять поиск по справке платформы 1С:Предприятие и получать детальную информацию о встроенных функциях, типах, методах и свойствах (аналогично работе с "Синтаксис-помощником" или официальной документацией 1С).

### 🤖 Возможности MCP сервера

- **Поиск по справке платформы 1С** — нечеткий поиск по встроенным функциям, методам, свойствам и типам данных
- **Детальная справка** — получение подробной информации о функциях, методах, свойствах и типах, включая сигнатуры и описания
- **Навигация по объектной модели** — просмотр методов и свойств конкретных типов данных
- **Информация о конструкторах** — способы создания объектов платформы 1С
- **Интеграция с AI** — стандартизированный протокол MCP для взаимодействия с AI-ассистентами
- **Два режима работы** — STDIO для локальной разработки и SSE для сетевого доступа

Проект использует Spring Boot и Spring AI для создания MCP сервера на базе Kotlin.

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

### STDIO режим (по умолчанию)
- **Назначение** — локальная интеграция с MCP клиентами
- **Транспорт** — стандартный ввод/вывод (stdin/stdout)
- **Применение** — Claude Desktop, Cursor IDE, VS Code
- **Преимущества** — простота настройки, низкие накладные расходы

### SSE режим (Server-Sent Events)
- **Назначение** — сетевая интеграция и веб-интерфейс
- **Транспорт** — HTTP с Server-Sent Events
- **Применение** — веб-клиенты, удаленные подключения, REST API
- **Преимущества** — сетевой доступ, встроенный веб-интерфейс, real-time коммуникация

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

### Системные требования
- **Java**: версия 17 или выше
- **Операционная система**: Linux, macOS, Windows
- **Память**: минимум 512 МБ RAM для работы приложения
- **Место на диске**: 100 МБ для установки приложения

### Для MCP сервера
- **Платформа 1С Предприятие**: версия 8.3.20 или выше (рекомендуется)
- **MCP клиент**: Claude Desktop, Cursor IDE или другой совместимый MCP клиент
- **Сетевое подключение**: для загрузки зависимостей при первом запуске

### Зависимости времени выполнения
Все необходимые зависимости включены в исполняемый JAR-файл:
- Spring Boot 3.5.0
- Spring AI 1.0.0
- Jackson 2.15.2
- Kotlin Coroutines

## Сборка

Проект собирается с помощью Gradle. Для сборки выполните следующую команду в корневой директории проекта:

```bash
./gradlew build
```

После успешной сборки исполняемый JAR-файл будет находиться в директории `build/libs/`.

## Использование

### Запуск MCP сервера

Linux
```bash
java -jar mcp-bsl-context-<версия>.jar [опции]
```
Windows
```bash
java -Dfile.encoding=UTF-8 -jar mcp-bsl-context-<версия>.jar [опции]
```

**Опции:**

- `--platform-path`, `-p` - путь к каталогу установки 1С Предприятия
- `--help`, `-h` - показать справку по использованию
- `--verbose` - включить отладочное логирование
- `--mode`, `-m` - режим работы: sse (HTTP Server-Sent Events) или stdio (стандартный ввод/вывод) (по умолчанию stdio)
- `--port` - порт для SSE сервера (по умолчанию 8080)

**Примеры:**

```bash
# STDIO режим (по умолчанию)
java -jar mcp-bsl-context-0.3.0.jar --platform-path "/opt/1cv8/x86_64/8.3.25.1257"

# SSE режим (HTTP Server-Sent Events)
java -jar mcp-bsl-context-0.3.0.jar --mode sse --platform-path "/opt/1cv8/x86_64/8.3.25.1257"

# SSE режим с кастомным портом
java -jar mcp-bsl-context-0.3.0.jar --mode sse --port 9000 --platform-path "/opt/1cv8/x86_64/8.3.25.1257"

# Сокращенная форма
java -jar mcp-bsl-context-0.3.0.jar -m stdio -p "/opt/1cv8/x86_64/8.3.25.1257"

# Показать справку
java -jar mcp-bsl-context-0.3.0.jar --help
```

**Примеры запуска в Windows:**

```cmd
# STDIO режим (по умолчанию)
java -Dfile.encoding=UTF-8 -jar mcp-bsl-context-0.3.0.jar --platform-path "C:\Program Files\1cv8\8.3.27.1606"
```

### Возможности MCP сервера

#### Инструменты (Tools) доступные через MCP:

- **search** - поиск по API платформы 1С Предприятие
- **info** - получение детальной информации об элементе API  
- **getMember** - получение информации о методе или свойстве конкретного типа
- **getMembers** - получение полного списка всех методов и свойств для указанного типа
- **getConstructors** - получение списка конструкторов для указанного типа

Подробная документация по использованию MCP сервера доступна в [MCP_SERVER_USAGE.md](documentation/README.md).

## Интеграция с AI клиентами

### STDIO режим (по умолчанию)
Для локального использования с AI клиентами через stdin/stdout.

**Claude Desktop** - добавьте конфигурацию в `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "1c-platform": {
      "command": "java",
      "args": [
        "-jar", 
        "/path/to/mcp-bsl-context.jar", 
        "--platform-path", 
        "/opt/1cv8/x86_64/8.3.25.1257"
      ]
    }
  }
}
```
Пример настройки для работы в Windows 
```json
  "mcpServers": {
    "1c-platform": {
      "type": "stdio",
      "command": "java",
      "args": [
        "-Dfile.encoding=UTF-8",
        "-jar",
        "C:\\your_path\\mcp-bsl-context-0.3.0.jar",
        "--platform-path",
        "C:\\Program Files\\1cv8\\8.3.27.1606"
      ],
      "env": {
        "LOG_FILE": "C:\\cmd\\mcp-server.log"
      }
    }
}
```

**Cursor IDE** - создайте файл `.cursor/mcp.json` в корне проекта:

```json
{
  "mcpServers": {
    "1c-platform": {
      "command": "java",
      "args": [
        "-jar", 
        "/path/to/mcp-bsl-context.jar", 
        "--platform-path", 
        "/opt/1cv8/x86_64/8.3.25.1257"
      ]
    }
  }
}
```
Пример настройки для работы в Windows 
```json
  "mcpServers": {
    "1c-platform": {
      "type": "stdio",
      "command": "java",
      "args": [
        "-Dfile.encoding=UTF-8",
        "-jar",
        "C:\\your_path\\mcp-bsl-context-0.3.0.jar",
        "--platform-path",
        "C:\\Program Files\\1cv8\\8.3.27.1606"
      ],
      "env": {
        "LOG_FILE": "C:\\cmd\\mcp-server.log"
      }
    }
}
```

### SSE режим (HTTP Server-Sent Events)
Для сетевого доступа и веб-интерфейса.

**Запуск сервера:**
```bash
java -jar mcp-bsl-context.jar --mode sse --platform-path "/opt/1cv8/x86_64/8.3.25.1257"
```

**Доступные эндпоинты:**
- `http://localhost:8080/sse` - SSE соединение

**Подключение через URL:**
```json
{
  "mcpServers": {
    "1c-platform-sse": {
      "url": "http://localhost:8080/mcp/sse"
    }
  }
}
```

**Пример HTTP запроса:**
```bash
curl -X POST http://localhost:8080/mcp/request \
  -H "Content-Type: application/json" \
  -d '{
    "id": "req-1",
    "method": "search",
    "params": {
      "query": "СтрНайти",
      "type": "method",
      "limit": 5
    }
  }'
```

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

- [Обзор](documentation/00_OVERVIEW.md) - общий обзор и быстрый старт
- [Возможности](documentation/01_CAPABILITIES.md) - описание доступных инструментов и функций
- [Установка и запуск](documentation/02_SETUP.md) - инструкции по установке и настройке
- [Docker](documentation/03_DOCKER.md) - работа с Docker контейнерами
- [Техническая документация](documentation/04_TECHNICAL.md) - архитектура и технические детали
- [Интеграция](documentation/05_INTEGRATION.md) - интеграция с IDE и AI клиентами
- [SSE режим](documentation/SSE_USAGE.md) - подробная документация по SSE режиму
- [Использование MCP сервера](documentation/README.md) - базовое использование

## Алгоритм поиска

Поиск выполняется по принципу нечеткого соответствия с ранжированием:

1. **Точное совпадение** (100 баллов) - имя полностью совпадает с запросом
2. **Префиксное совпадение** (80 баллов) - имя начинается с запроса  
3. **Частичное совпадение** (60 баллов) - имя содержит запрос
4. **Совпадение в сигнатуре** (40 баллов) - запрос найден в сигнатуре
5. **Совпадение в описании** (20 баллов) - запрос найден в описании
6. **Fuzzy matching** (0-50 баллов) - на основе расстояния Левенштейна

## Зависимости

Основные зависимости проекта:

- Spring Boot 3.5.0
- Spring AI MCP Server
- Kotlin с Coroutines
- Jackson (для работы с JSON)
- Logback для логирования

## Использованные идеи

Алгоритм чтения справки базируется на идеях [bsl-context](https://github.com/1c-syntax/bsl-context) (от [1c-syntax](https://github.com/1c-syntax/)).

## Лицензия

Этот проект распространяется под лицензией MIT. Подробную информацию смотрите в файле [LICENSE](LICENSE).