Content
# MCP server for AI assistants (syntax help and object model 1C:Enterprise)
**MCP (Model Context Protocol) server** is a tool for integration with AI assistants (e.g., Claude Desktop, Cursor IDE), providing fast and standardized access to reference information on built-in functions, data types, methods, and properties of the 1C:Enterprise platform. MCP server allows AI assistants to work with 1C's "Syntax Assistant" in interactive mode.
## Overview
The `mcp-bsl-context` application is designed exclusively for integration with AI assistants, so that they can search the 1C:Enterprise platform help and obtain detailed information about built-in functions, types, methods, and properties (similar to working with the "Syntax Assistant" or official 1C documentation).
### 🤖 MCP server features
- **Search 1C platform help** - fuzzy search for built-in functions, methods, properties, and data types
- **Detailed help** - getting detailed information about functions, methods, properties, and types, including signatures and descriptions
- **Object model navigation** - viewing methods and properties of specific data types
- **Constructor information** - ways to create 1C platform objects
- **AI integration** - standardized MCP protocol for interacting with AI assistants
- **Two operation modes** - STDIO for local development and SSE for network access
The project uses Spring Boot and Spring AI to create an MCP server based on Kotlin.
## Operating modes
### STDIO mode (default)
- **Purpose** - local integration with MCP clients
- **Transport** - standard input/output (stdin/stdout)
- **Application** - Claude Desktop, Cursor IDE, VS Code
- **Advantages** - ease of setup, low overhead
### SSE mode (Server-Sent Events)
- **Purpose** - network integration and web interface
- **Transport** - HTTP with Server-Sent Events
- **Application** - web clients, remote connections, REST API
- **Advantages** - network access, built-in web interface, real-time communication
## Requirements
### System requirements
- **Java**: version 17 or higher
- **Operating system**: Linux, macOS, Windows
- **Memory**: minimum 512 MB RAM for the application to work
- **Disk space**: 100 MB for application installation
### For MCP server
- **1C:Enterprise platform**: version 8.3.20 or higher (recommended)
- **MCP client**: Claude Desktop, Cursor IDE or other compatible MCP client
- **Network connection**: to download dependencies on first launch
### Runtime dependencies
All necessary dependencies are included in the executable JAR file:
- Spring Boot 3.5.0
- Spring AI 1.0.0
- Jackson 2.15.2
- Kotlin Coroutines
## Build
The project is built using Gradle. To build, run the following command in the root directory of the project:
```bash
./gradlew build
```
After a successful build, the executable JAR file will be located in the `build/libs/` directory.
## Usage
### Running the MCP server
Linux
```bash
java -jar mcp-bsl-context-<version>.jar [options]
```
Windows
```bash
java -Dfile.encoding=UTF-8 -jar mcp-bsl-context-<version>.jar [options]
```
**Options:**
- `--platform-path`, `-p` - path to the 1C:Enterprise installation directory
- `--help`, `-h` - show usage help
- `--verbose` - enable debug logging
- `--mode`, `-m` - operating mode: sse (HTTP Server-Sent Events) or stdio (standard input/output) (default stdio)
- `--port` - port for SSE server (default 8080)
**Examples:**
```bash
# STDIO mode (default)
java -jar mcp-bsl-context-0.3.0.jar --platform-path "/opt/1cv8/x86_64/8.3.25.1257"
# SSE mode (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 mode with custom port
java -jar mcp-bsl-context-0.3.0.jar --mode sse --port 9000 --platform-path "/opt/1cv8/x86_64/8.3.25.1257"
# Abbreviated form
java -jar mcp-bsl-context-0.3.0.jar -m stdio -p "/opt/1cv8/x86_64/8.3.25.1257"
# Show help
java -jar mcp-bsl-context-0.3.0.jar --help
```
**Windows startup examples:**
```cmd
# STDIO mode (default)
java -Dfile.encoding=UTF-8 -jar mcp-bsl-context-0.3.0.jar --platform-path "C:\Program Files\1cv8\8.3.27.1606"
```
### MCP server features
#### Tools available via MCP:
- **search** - search the 1C:Enterprise platform API
- **info** - get detailed information about an API element
- **getMember** - get information about a method or property of a specific type
- **getMembers** - get a complete list of all methods and properties for the specified type
- **getConstructors** - get a list of constructors for the specified type
Detailed documentation on using the MCP server is available in [MCP_SERVER_USAGE.md](documentation/README.md).
## Integration with AI clients
### STDIO mode (default)
For local use with AI clients via stdin/stdout.
**Claude Desktop** - add configuration to `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"
]
}
}
}
```
Example settings for working in 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** - create a `.cursor/mcp.json` file in the project root:
```json
{
"mcpServers": {
"1c-platform": {
"command": "java",
"args": [
"-jar",
"/path/to/mcp-bsl-context.jar",
"--platform-path",
"/opt/1cv8/x86_64/8.3.25.1257"
]
}
}
}
```
Example settings for working in 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 mode (HTTP Server-Sent Events)
For network access and web interface.
**Starting the server:**
```bash
java -jar mcp-bsl-context.jar --mode sse --platform-path "/opt/1cv8/x86_64/8.3.25.1257"
```
**Available endpoints:**
- `http://localhost:8080/sse` - SSE connection
**Connecting via URL:**
```json
{
"mcpServers": {
"1c-platform-sse": {
"url": "http://localhost:8080/mcp/sse"
}
}
}
```
**HTTP request example:**
```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
- [Overview](documentation/00_OVERVIEW.md) - general overview and quick start
- [Capabilities](documentation/01_CAPABILITIES.md) - description of available tools and functions
- [Setup](documentation/02_SETUP.md) - installation and setup instructions
- [Docker](documentation/03_DOCKER.md) - working with Docker containers
- [Technical documentation](documentation/04_TECHNICAL.md) - architecture and technical details
- [Integration](documentation/05_INTEGRATION.md) - integration with IDEs and AI clients
- [SSE mode](documentation/SSE_USAGE.md) - detailed documentation on SSE mode
- [Using the MCP server](documentation/README.md) - basic usage
## Search algorithm
The search is performed on the principle of fuzzy matching with ranking:
1. **Exact match** (100 points) - the name fully matches the query
2. **Prefix match** (80 points) - the name starts with the query
3. **Partial match** (60 points) - the name contains the query
4. **Match in signature** (40 points) - the query is found in the signature
5. **Match in description** (20 points) - the query is found in the description
6. **Fuzzy matching** (0-50 points) - based on Levenshtein distance
## Dependencies
Main project dependencies:
- Spring Boot 3.5.0
- Spring AI MCP Server
- Kotlin with Coroutines
- Jackson (for working with JSON)
- Logback for logging
## Used ideas
The help reading algorithm is based on the ideas of [bsl-context](https://github.com/1c-syntax/bsl-context) (from [1c-syntax](https://github.com/1c-syntax/)).
## License
This project is distributed under the MIT license. See the [LICENSE](LICENSE) file for details.
