MCP Db Client

http1c--1C的MCP服务器框架：企业

http1c 是一个建筑框架 模型上下文协议（MCP） 1C的服务器：企业。它提供了一个处理MCP传输层的本机组件（DLL）和一个演示如何实现工具、资源和提示的参考1C数据处理器。

将其用作模板，将任何1C业务逻辑（目录、文档、报告、计算）暴露给VS Code Copilot、Claude Desktop和其他MCP兼容客户端等AI应用程序。

核心概念

该项目有意分为两层，分别承担不同的责任。

本地组件责任

DLL是MCP引擎。它处理不应在1C业务代码中重新实现的协议和传输细节：

• HTTP/SSE传输
• JSON-RPC请求/响应生命周期
• MCP会话管理
• 身份验证、来源验证和速率限制
• 分页、通知和进度流
• 将1C响应转换为有效的MCP响应

1C职责

1C侧拥有业务逻辑。1C开发人员应该在工具、资源和提示级别工作，而不是在MCP内部级别工作：

• 在BSL中描述工具/资源/提示
• 在组件中注册它
• 在1C中处理来电
• 运行任何所需的客户端或服务器端1C逻辑
• 返回结果或发送进度更新

为什么项目是这样设计的

目标是让1C开发人员通过MCP发布几乎任何1C功能，而无需了解HTTP、JSON-RPC、SSE、会话处理或MCP消息格式。

换言之：

• 该组件知道如何成为MCP服务器
• 1C知道工具的实际功能

这使集成点保持简单。要添加新功能，1C开发人员不需要更改本机传输层。它们只添加或更新1C定义和处理程序。

1C开发人员的心智模型

从1C的角度来看，工作流程故意简单：

1. 在BSL中定义MCP对象。
2. 在组件中注册它。
3. 通过接收请求 ExternalEvent.
4. 执行任意1C逻辑。
5. 返回最终结果，并可选择在操作运行时发送进度。

这意味着该项目不是一组固定的内置实用程序。它是1C的MCP传输和协议层，实际应用行为在1C代码中定义。

主要特点

• 完全支持MCP协议 --工具、资源、提示 listChanged 通知
• 可流式HTTP传输 — POST /mcp 对于请求， GET /mcp 用于SSE通知流
• 会话管理 — Mcp-Session-Id 标头，每个规范的UUID v4会话
• 安全 --源验证（DNS重新绑定保护）、承载令牌认证、速率限制
• 进度流 --基于SSE的长时间运行的进度通知
• 分页 --基于光标的分页 tools/list, resources/list, prompts/list
• 工具注释 — readOnlyHint, destructiveHint, idempotentHint, openWorldHint
• 输出模式 --工具结果的类型化响应合同
• 动态注册 --从1C开始在运行时注册/更新工具、资源和提示

建筑

┌─────────────────┐     HTTP/SSE      ┌──────────────────┐    ExternalEvent   ┌──────────────────┐
│   MCP Client    │◄─────────────────►│   Native DLL     │◄──────────────────►│  1C:Enterprise   │
│  (VS Code, etc) │   POST/GET /mcp   │  (HttpServer)    │   ToolCall, etc.   │  (BSL Module)    │
└─────────────────┘                   └──────────────────┘                    └──────────────────┘

1. 1C表单加载本机外接程序并启动HTTP服务器。
2. MCP客户端连接到 http://localhost:PORT/mcp.
3. 本机组件处理协议级消息（初始化、工具/列表等）。
4. 业务逻辑请求（工具/调用、资源/读取、提示/获取）通过以下方式转发给1C ExternalEvent.
5. 1C模块处理请求并通过以下方式发送结果 SendResponse.
6. DLL将结果封装在JSON-RPC响应中，并将其返回给客户端。

快速开始

1.构建DLL

build/build-http1c-dll-release.sh

需要支持C++的Visual Studio构建工具2019+。

2.打包插件

打包在构建脚本结束时自动完成。要独立运行它，请执行以下操作：

build/package-http1c-addin.sh

3.编译EPF（需要OneScript）

build/compile-http1c-epf.sh

4.在1C中打开

1. 打开 http1c.epf 1C信息库中的数据处理器。
2. 点击 连接 --MCP服务器在配置的端口上启动。
3. 配置您的MCP客户端以连接到 http://localhost:PORT/mcp.

5.VS代码配置

添加到您的 .vscode/mcp.json:

无身份验证：

{
  "servers": {
    "1c-mcp-server": {
      "type": "sse",
      "url": "http://localhost:8888/mcp"
    }
  }
}

使用Bearer令牌身份验证：

{
  "servers": {
    "1c-mcp-server": {
      "type": "sse",
      "url": "http://localhost:8888/mcp",
      "headers": {
        "Authorization": "Bearer ${input:mcpToken}"
      }
    }
  },
  "inputs": [
    {
      "id": "mcpToken",
      "type": "promptString",
      "description": "Bearer token for the 1C MCP server",
      "password": true
    }
  ]
}

使用时 ${input:...} 语法，每次MCP服务器连接启动时，VS Code都会提示输入令牌。输入的值被屏蔽为密码。

重要提示： VS Code中的令牌必须与1C侧设置的值匹配。如果服务器没有配置令牌（空字符串），则身份验证被禁用，并且没有 headers 需要。如果服务器上设置了令牌，但VS Code没有发送 Authorization 头，服务器用HTTP 401响应，VS Code可能会尝试启动OAuth流——这是不支持的；使用 headers 取而代之的是上面的方法。

如何从1C构建自己的MCP服务器

参考数据处理器(http-1c-dp)这是一个工作示例。以此为起点：

注册工具

工具是AI客户端可以调用的可执行函数。将它们定义为JSON结构并向组件注册：

// Create a tool definition
Tool = NewTool("myTool", "Description of what this tool does");
AddToolParam(Tool, "paramName", "string", "Parameter description");
AddToolAnnotations(Tool, True);  // readOnly, safe

// Define output schema (optional, helps clients validate responses)
Schema = NewOutputSchema();
AddOutputProperty(Schema, "result", "string", "Result description");
SetToolOutputSchema(Tool, Schema);

// Register all tools
Tools = New Array;
Tools.Add(Tool);
Await Component.RegisterToolsAsync(SerializeToJson(Tools));

在中处理工具调用 ExternalEvent 处理程序：

&AtClient
Async Procedure ExternalEvent(Source, Event, Data)
    If Source <> "HttpServer" Then Return; EndIf;
    If Event = "ToolCall" Then ProcessToolCall(Data); EndIf;
EndProcedure

注册资源

资源为AI客户端提供上下文数据（元数据、文件内容等）：

Resource = New Structure;
Resource.Insert("uri", "1c://metadata/catalogs");
Resource.Insert("name", "1C Catalogs");
Resource.Insert("description", "List of all catalog metadata objects");
Resource.Insert("mimeType", "application/json");

Resources = New Array;
Resources.Add(Resource);
Await Component.RegisterResourcesAsync(SerializeToJson(Resources));

处理资源读取 "ResourceRead" 事件。

注册提示

提示是可重用的交互模板：

Prompt = New Structure;
Prompt.Insert("name", "analyzeData");
Prompt.Insert("description", "Prompt for analyzing 1C data");

PromptArgs = New Array;
Arg = New Structure("name,description,required", "topic", "Analysis topic", False);
PromptArgs.Add(Arg);
Prompt.Insert("arguments", PromptArgs);

Prompts = New Array;
Prompts.Add(Prompt);
Await Component.RegisterPromptsAsync(SerializeToJson(Prompts));

处理提示通过 "PromptGet" 事件。

动态更新

呼叫 RegisterToolsAsync() / RegisterResourcesAsync() / RegisterPromptsAsync() 随时更新列表。组件将自动发送 notifications/tools/list_changed （或同等产品）连接到所有连接的MCP客户端。

安全配置

该组件支持可选的承载令牌身份验证。当设置令牌时，每个HTTP请求都必须包含 Authorization: Bearer 否则它将被HTTP 401拒绝。

// Enable authentication — all requests must include Authorization: Bearer my-secret-token
Component.AuthToken = "my-secret-token";

// Disable authentication — any request is accepted
Component.AuthToken = "";

它是如何工作的：

在运行时更改令牌： 您可以设置或清除 AuthToken 当服务器正在运行时。该更改对所有新请求立即生效，无需重新启动。

VS代码注释： 如果服务器返回401，VS Code可能会尝试OAuth 2.0 PKCE授权流（重定向到 /authorize).这是 不支持 根据组件。始终在中配置令牌 .vscode/mcp.json 通过 headers 字段（参见 VS代码配置 上文）。

该组件还强制执行：

• 原产地验证 --仅来自的请求 localhost / 127.0.0.1 /VS代码来源被接受
• 速率限制 --令牌桶算法（60突发，20/sec）
• 会话管理 — Mcp-Session-Id 在初始化时分配，在后续请求时验证

本机组件API

暴露于1C的方法（英文/俄文名称）：

暴露于1C的特性：

外部事件类型

从本机组件发送到1C的事件：

MCP协议支持

已实施的方法

功能广告

{
  "tools": { "listChanged": true },
  "resources": { "listChanged": true },
  "prompts": { "listChanged": true }
}

HTTP端点

参考工具（演示处理器中）

参考资料

参考提示

仓库的规划

├── build/
│   ├── build-http1c-dll-debug.sh       # Build DLL in debug mode
│   ├── build-http1c-dll-release.sh     # Build DLL in release mode
│   ├── compile-http1c-epf.sh           # Compile EPF from XML
│   ├── package-http1c-addin.sh         # Package DLL as 1C add-in ZIP
│   └── onescript/
│       └── compile-external-processor.os
├── http-1c-dll/
│   ├── CMakeLists.txt                  # CMake build configuration
│   ├── version.h                       # Version management
│   ├── include/                        # 1C API headers + vendored libraries
│   │   ├── httplib.h                   # cpp-httplib (HTTP server)
│   │   ├── json.hpp                    # nlohmann/json (JSON parser)
│   │   └── AddInDefBase.h, ...         # 1C Native API headers
│   └── src/
│       ├── AddInNative.cpp/h           # Generic 1C add-in framework
│       ├── HttpServerComponent.cpp/h   # MCP server implementation
│       └── AddInNative.def             # DLL export definitions
├── http-1c-dp/
│   ├── http1c.xml                      # 1C data processor XML source
│   └── http1c/
│       └── Forms/Form/Ext/Form/
│           └── Module.bsl              # Reference MCP server implementation
└── http1c.epf                          # Compiled 1C external data processor

技术栈

• C++17 --本地组件
• CMake + 微软VC编译器 --构建系统
• cpp httplib --嵌入式HTTP服务器
• nlohmann/json --JSON解析器
• 1C本机API --与1C集成：企业
• OneScript --从XML编译EPF

基于 门楣/添加模板 对于本机插件层。

许可证

看 许可证.

构建要求

签入的生成脚本以Windows为目标。

所需工具：

• Microsoft Visual Studio Build Tools 2019+与MSVC（C++工作负载）-必须手动安装（系统级，需要管理员）
• CMake和Ninja——自动下载到 build/tools/ 如果在PATH中找不到，则在首次运行时

设置新的开发人员计算机

完整的Visual Studio 不 必需的——免费的独立构建工具就足够了，它们是 你唯一需要手动安装的东西.

通过安装 winget （运行一次，需要管理员）：

winget install Microsoft.VisualStudio.2022.BuildTools --override "--quiet --add Microsoft.VisualStudio.Workload.VCTools --includeRecommended"

或者通过巧克力：

choco install visualstudio2022buildtools --package-parameters "--add Microsoft.VisualStudio.Workload.VCTools --includeRecommended" -y

或者从手动下载安装程序https://visualstudio.microsoft.com/downloads/#build-工具-视觉研究-2022，然后选择 “用C++进行桌面开发” 工作量。

之后，只需运行一个构建脚本——CMake和Ninja将自动下载到 build/tools/ 第一次使用。

构建DLL

发布版本：

build/build-http1c-dll-release.sh

调试版本：

build/build-http1c-dll-debug.sh

DLL输出将写入：

http-1c-dll/bin/libhttp1cWin.dll

调试符号也被写入 http-1c-dll/bin/.

成功构建DLL后，顶级构建脚本还将本机外接程序包打包为 MANIFEST.XML 元数据，并在此处更新嵌入式1C模板：

http-1c-dp/http1c/Templates/http1c/Ext/Template.bin

运行1C侧

存储库包括一个外部数据处理器：

• http-1c-dp/http1c.epf

其表单模块负责：

• 附加本地插件，
• 启动HTTP侦听器，
• 注册MCP工具，
• 处理从DLL转发的请求，
• 将响应和进度消息发送回DLL。

该加载项是从嵌入式1C模板而不是特定于机器的DLL路径附加的。

日志记录

默认日志文件不再是硬编码的绝对路径。

http_debug.log

在本机端，当1C没有提供显式日志路径时，组件会回退到系统临时目录。

%TEMP%\http1c.log

在连接之前，您仍然可以通过表单字段覆盖日志路径。

VS代码MCP配置

工作区已包含示例MCP客户端配置：

{
  "servers": {
    "ConnectionTo1C": {
      "type": "sse",
      "url": "http://localhost:8888/mcp"
    }
  }
}

这与未设置自定义端口时1C窗体使用的默认侦听器端口相匹配。

典型的本地工作流程

1. 构建 http-1c-dll.
2. 打开 http-1c-dp/http1c.epf 1C：企业。
3. 可选择调整窗体中的端口和日志路径。
4. 从嵌入式模板中附加外接程序。
5. 启动本地监听器。
6. 使用VS Code的MCP服务器或其他支持MCP的客户端。

现在从顶级构建文件夹启动XML源的EPF编译：

build/compile-http1c-epf.sh

编译后的处理器工件被写入存储库根目录：

http1c.epf

局限和警告

• 以Windows为中心的安装程序。构建脚本通过bash面向MSVC和NMake。
• 构建仍然取决于Windows工具链的可用性 PATH 或初始化的Visual Studio构建环境。
• HTTP服务器故意只在本地，并绑定到 127.0.0.1.
• execute 和 evaluate 暴露了强大的服务器端功能，只应在受信任的本地环境中使用。
• 当前的工具集将实用助手与演示功能混合在一起，例如 runLongTask.
• 目前还没有打包或部署流程来将插件作为优化产品分发。

测试和部署说明

在开发过程中更新本机加载项DLL时：

1. 清除组件缓存。 1C将本机加载项缓存在临时目录中。在加载新版本之前删除缓存文件夹：

   %APPDATA%\1C\1cv8\ExtCompT

1. 重新启动1C会话。 完全关闭1C应用程序并重新打开它——正在运行的会话会锁定旧的DLL。
2. 禁用危险动作保护。 在1C用户设置中，取消选中 *“防止危险行为”* (Защита от опасных действий).否则，平台将阻止加载项附件。

如果没有这些步骤，平台可能会静默加载过时的DLL或拒绝附加外接程序。

版本

源代码中定义的本机组件版本为：

1.3.0

许可证

该项目根据MIT许可证获得许可。看 LICENSE.