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

用于将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: 1C_MCP_SERVER_OWN

快速开始

方案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检查。

ask_1c_ai

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

review_1c_code

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

rewrite_1c_code

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

modify_1c_code

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

explain_1c_syntax

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

文档与帮助

its_help

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

fetch_its

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

search_1c_documentation

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

onec_help

搜索平台文档（最新版本）。与search_1c_documentation相同，但不指定版本。

diff_1c_documentation_versions

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

config_help

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

配置

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

* 必须设置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响应格式：

此外：

• 自动从响应中移除<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

致谢

• comol/1c-code-checker - 原始想法（仓库已关闭）

• SteelMorgan/spring-mcp-1c-copilot - 正确的API算法

• FastMCP - MCP服务器框架

许可证

MIT - 参见LICENSE