Content
# 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).
