Skip to main content
Glama

1C AI MCP - 用于1C:Напарник的MCP服务器

Docker Hub License

用于将IDE与1С:Напарник API集成的MCP服务器(Model Context Protocol)。基于FastMCP(Python)构建,打包为Docker。可与Cursor、Claude Code及任何MCP兼容客户端配合使用。

12个工具:代码分析(检查、审查、重构)和文档搜索(ITS、平台、配置)。

基于comol/1c-code-checker的想法,并采用了SteelMorgan/spring-mcp-1c-copilot中修正的API格式(422错误)算法。

前置要求

  • Docker(或Docker Desktop)

  • 1С:Напарник令牌 - 在code.1c.ai获取(需要ITS订阅)

Related MCP server: xbsl-mcp

快速开始

方案A:使用Docker Hub现成镜像(推荐)

docker run -d --name 1c-ai-mcp -p 8007:8007 \
  -e ONEC_AI_TOKEN="ваш-токен" \
  desko77/1c-ai-mcp:latest

或通过Docker Compose - 创建docker-compose.yml文件:

services:
  1c-ai-mcp:
    image: desko77/1c-ai-mcp:latest
    container_name: 1c-ai-mcp
    ports:
      - "8007:8007"
    environment:
      ONEC_AI_TOKEN: "${ONEC_AI_TOKEN}"
    restart: always
# Создать .env с токеном (не попадает в git)
echo 'ONEC_AI_TOKEN=ваш-токен' > .env

# Запустить
docker compose up -d

方案B:从源码构建

git clone https://github.com/Desko77/1c-ai-mcp.git
cd 1c-ai-mcp

# Создать .env с токеном
echo 'ONEC_AI_TOKEN=ваш-токен' > .env

# Собрать и запустить
docker compose up -d --build

功能验证

# Должен вернуть HTTP 200
curl http://localhost:8007/mcp

连接IDE

Cursor

在~/.cursor/mcp.json中添加:

{
  "mcpServers": {
    "1c-naparnik": {
      "url": "http://localhost:8007/mcp"
    }
  }
}

Claude Code

在~/.claude/settings.json中添加:

{
  "mcpServers": {
    "1c-naparnik": {
      "url": "http://localhost:8007/mcp"
    }
  }
}

其他MCP客户端

端点:http://localhost:8007/mcp 传输方式:Streamable HTTP(默认)或SSE(USESSE=true)。

工具

代码分析

check_1c_code

1C代码检查:语法、逻辑、性能。在direct模式下,语法通过upstream syntax-checker检查。

参数

类型

描述

code

string

要检查的1C代码

check_type

string

syntax(默认)、logic、performance

ask_1c_ai

向1С:Напарник提出任意问题。在多次调用之间保存对话上下文。

参数

类型

描述

question

string

问题

create_new_session

bool

新会话(默认false - 复用之前的会话)

review_1c_code

代码审查:风格、ITS标准、命名、结构、可读性。不检查语法。

参数

类型

描述

code

string

要审查的1C代码

rewrite_1c_code

AI提供其改进后的代码版本,并附修改说明。

参数

类型

描述

code

string

要重写的1C代码

goal

string

方向:optimize、readability、error handling(可选)

modify_1c_code

根据明确指令修改代码。如果未指定代码 - 则生成新代码。

参数

类型

描述

instruction

string

所需修改的描述

code

string

源代码(可选)

explain_1c_syntax

解释1C语法的具体元素。

参数

类型

描述

syntax_element

string

语法元素

context

string

使用上下文(可选)

文档与帮助

its_help

搜索ITS知识库(标准、方法、文章)。返回用于fetch_its的文档ID。

参数

类型

描述

query

string

搜索查询

fetch_its

按标识符读取ITS文档。在its_help之后使用。

参数

类型

描述

id

string

文档ID(root、v8std、its-...-hdoc)

search_1c_documentation

搜索特定版本的1С:Предприятие平台文档。

参数

类型

描述

query

string

搜索查询

version

string

版本(默认v8.5.1)

onec_help

搜索平台文档(最新版本)。与search_1c_documentation相同,但不指定版本。

参数

类型

描述

query

string

搜索查询

diff_1c_documentation_versions

比较两个版本之间的平台文档。

参数

类型

描述

version_a

string

较早版本(例如v8.3.25)

version_b

string

较晚版本(例如v8.5.1)

query

string

主题领域(可选)

config_help

搜索应用配置文档(ERP、会计、ZUP、UT等)。

参数

类型

描述

query

string

搜索查询

config_name

string

配置名称(可选,取自ONEC_CONFIG_NAME)

配置

所有参数通过环境变量传递。

变量

必填

默认值

描述

ONEC_AI_TOKEN

是*

-

1С:Напарник API令牌

ONEC_AI_TOKEN_FILE

否

-

令牌文件路径(Docker Secrets)

ONEC_AI_BASE_URL

否

https://code.1c.ai

API基础URL

ONEC_AI_SKILL_NAME

否

raw

对话技能(raw、custom)

ONEC_AI_AUTH_FORMAT

否

plain

Authorization格式:plain或bearer

ONEC_AI_TIMEOUT

否

120

HTTP请求超时(秒)

ONEC_CONFIG_NAME

否

-

用于config_help的配置(例如ERP、ЗУП)

MCP_TOOL_CALL_MODE

否

standard

模式:standard(提示词)/ direct(直接调用upstream)

ONEC_AI_INPUT_MAX_LENGTH

否

100000

输入数据最大长度(字符)

HTTP_PORT

否

8007

MCP服务器端口

USESSE

否

false

传输方式:true=SSE,false=streamable-http

MAX_ACTIVE_SESSIONS

否

10

并发会话限制

SESSION_TTL

否

3600

会话TTL(秒)

LOG_LEVEL

否

INFO

日志级别(DEBUG、INFO、WARNING)

* 必须设置ONEC_AI_TOKEN或ONEC_AI_TOKEN_FILE。

Docker Secrets

对于生产环境,令牌可以通过文件传递:

services:
  1c-ai-mcp:
    image: desko77/1c-ai-mcp:latest
    environment:
      ONEC_AI_TOKEN_FILE: /run/secrets/onec_token
    secrets:
      - onec_token

secrets:
  onec_token:
    file: ./onec_token.txt

Direct模式

当MCP_TOOL_CALL_MODE=direct时,文档工具和check_1c_code(syntax)直接按名称调用1С:Напарник的upstream工具,而不是使用文本提示词。这样可以获得更精确的结果。

Upstream工具:

  • mcp__knowledge-hub__Search_ITS - 用于its_help

  • mcp__knowledge-hub__Fetch_ITS - 用于fetch_its

  • mcp__knowledge-hub__Search_Documentation - 用于search_1c_documentation、onec_help

  • mcp__knowledge-hub__Diff_Documentation_Versions - 用于diff_1c_documentation_versions

  • mcp__syntax-checker__validate - 用于check_1c_code(syntax)

direct调用失败时自动回退到提示词模式。默认为standard以保持向后兼容。

架构

MCP-клиент (Cursor / Claude Code)
  -> FastMCP HTTP endpoint (:8007/mcp)
    -> mcp_server.py (обработчики инструментов)
      -> OneCApiClient (HTTP-клиент)
        -> code.1c.ai API (SSE-стриминг)
          -> парсинг ответа -> возврат клиенту

两种工作模式

  • Standard模式(默认):工具生成文本提示词并发送到API。文档工具使用工具链 - 模型自行决定调用哪个服务器端工具。

  • Direct模式(MCP_TOOL_CALL_MODE=direct):工具显式按名称请求特定的upstream工具,匹配响应并确认调用。失败时自动回退到standard模式。

SSE解析器

支持三种API响应格式:

格式

结构

类型

Legacy

{"content_delta": "文本"}

增量式

OpenAI-like

{"choices": [{"delta": {"content": "文本"}}]}

增量式

Completed

{"content": {"text": "完整文本"}}

最终式

此外:

  • 自动从响应中移除<thinking>/ thinking块

  • Unicode规范化并清理控制字符

  • 收到tool_calls时的回退 - 使用skill_name="raw"重新请求

  • 按ONEC_AI_INPUT_MAX_LENGTH截断输入数据

开发

无需Docker的本地运行

pip install -r requirements.txt
export ONEC_AI_TOKEN="ваш-токен"
python main.py

项目结构

main.py                       # Точка входа
src/
  mcp_server.py                # MCP-инструменты (@mcp.tool)
  onec_api_client.py           # HTTP-клиент к API 1С:Напарник
Dockerfile                     # Dockerfile
docker-compose.yml             # Compose для сборки из исходников
tests/                         # Тестовые скрипты
.github/workflows/
  docker-publish.yml           # CI: сборка и публикация в Docker Hub

致谢

许可证

MIT - 参见LICENSE

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Provides a RAG-based search system for 1C:Enterprise platform documentation using hybrid BM25 and semantic search across multiple versions. It enables developers to retrieve API signatures, methods, and usage examples directly within IDEs or through a REST API.
      22
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Provides AI assistants in Cursor with local access to 1C platform documentation and XML configuration exports, enabling metadata lookup, BSL code search, and platform help queries without manual file copying.
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables agents and MCP clients to perform static analysis and code navigation on 1C (BSL) codebases, including diagnostics, callers/callees, definitions, references, complexity metrics, and reindexing.
      9
      MIT