内容
# 1C_MCP - MCP服务器端1С:企业
1C:企业信息库扩展程序，旨在将其转变为 **MCP服务器端** （Model Context Protocol），以便与AI助手（如Cursor，Claude Desktop等）以及其他MCP客户端进行集成。
代码仓库：[github.com/DarkVaneker/1C_MCP](https://github.com/DarkVaneker/1C_MCP)
该项目基于 [vladimir-kharin/1c_mcp](https://github.com/vladimir-kharin/1c_mcp) 并扩展了两个工具，用于 **执行和检查代码**，直接在1C内置语言的上下文中。
## 与基础项目的区别
| 功能 | [1c_mcp](https://github.com/vladimir-kharin/1c_mcp) | 1C_MCP (此代码仓库) |
|---|---|---|
| MCP 工具 / 资源 / 提示 | ✓ | ✓ |
| 配置元数据操作 | ✓ | ✓ |
| **`execute_1c_code_simple`** - 简单代码片段执行 | — | ✓ |
| **`execute_1c_code_complex`** - 多功能模块构建和执行 | — | ✓ |
| 通过定时任务异步构建 `.epf` 队列 | — | ✓ |
## 工作原理
```
AI 客户端 (Cursor) ←→ Python MCP 代理 ←→ HTTP 服务 mcp_APIBackend ←→ 容器处理
```
- **HTTP 服务** `mcp_APIBackend` 实现 MCP 协议的 JSON-RPC API (`tools/list`, `tools/call`, `resources/*`, `prompts/*`)。
- **容器处理** 通过 `mcp_容器工具` 子系统注册工具。
- 建议使用基础项目的 **Python 代理** 来连接 AI 客户端 - 它解决了身份验证和 `stdio` 传输问题。
更多架构信息请参阅 [agents.md](agents.md)。
## MCP 工具
### 基础项目中的工具
| 工具 | 描述 |
|---|---|
| `list_metadata_objects` | 按类型和名称掩码列出元数据对象 |
| `get_metadata_structure` | 所选元数据对象的结构 |
| `get_report_details` | 报告变体的 SKD 和模块 |
### 新工具
#### `execute_1c_code_simple`
在当前会话中同步执行简单的、自成体系的代码片段。
**参数：**
| 参数 | 类型 | 必需 | 描述 |
|---|---|---|---|
| `code` | 字符串 | 是 | 1C 内置语言代码 |
| `context` | 字符串 | 否 | 执行前声明的变量 JSON（默认为 `{}`） |
**特点：**
- 支持单个过程或函数。
- 如果代码中有 `返回值`，则结果在响应中返回。
- 对数据库的更改在事务中执行，并可回滚。
**调用示例：**
```json
{
"code": "结果 = 2 + 2;\n返回值 结果;",
"context": "{}"
}
```
#### `execute_1c_code_complex`
异步构建代码到外部处理（`.epf`）并调用指定入口点。适用于代码包含多个过程/函数且无法拆分为多个 `execute_1c_code_simple` 调用。
**参数：**
| 参数 | 类型 | 必需 | 描述 |
|---|---|---|---|
| `code` | 字符串 | 是 | 具有多个过程/函数的模块代码 |
| `entry_point` | 字符串 | 是 | 调用导出过程或函数的名称 |
| `context` | 字符串 | 否 | 上下文变量和方法的参数 JSON（默认为 `{}`） |
**执行架构：**
```
execute_1c_code_complex
│
▼
mcp_代码检查队列 ──► 定时任务 mcp_代码检查
│ │
│ 构建 .epf (1cv8.exe)
│ 执行 entry_point
▼ ▼
轮询结果 ◄──────────── 结果记录
```
> **重要：** 要使用 `execute_1c_code_complex`，1C 服务器上的定时任务 `mcp_代码检查` 必须启用，并且用户/ras 必须具有启动 `1cv8.exe` 的权限以构建外部处理。
## 代码仓库结构
```
1C_MCP/
├── README.md # 此文件
├── LICENSE # 许可证（附加组件的非商业使用）
├── agents.md # MCP 工具开发指南
├── bslrules.mdc # 1C 的 AI 助手（Cursor）规则
├── MCP_服务器.cfe # 安装的现成扩展
└── MCP_服务器_导出/ # 扩展导出（EDT / 配置器）
├── Configuration.xml
├── HTTPServices/mcp_APIBackend/
├── CommonModules/
├── DataProcessors/
├── InformationRegisters/mcp_代码检查队列/
└── ScheduledJobs/mcp_代码检查/
```
## 快速入门
### 要求
- 1C:企业平台 **8.3.20** 及更高版本（扩展兼容性模式：8.3.20）
- 已发布的 `mcp_APIBackend` HTTP 服务在 Web 服务器上
- Python MCP 代理 - 请参阅 [基础项目文档](https://github.com/vladimir-kharin/1c_mcp)
### 1. 安装扩展
1. 从代码仓库根目录下载现成的 [MCP_服务器.cfe] 文件。
2. 通过 **配置 → 配置扩展 → 从文件添加** 将 **MCP_服务器** 扩展连接到您的信息库。
3. 确保用户已分配 `mcp_基本角色`。
要从源代码开发和构建，请使用 `MCP_服务器_导出/` 目录。
### 2. 配置定时任务
对于 `execute_1c_code_complex` 工具：
1. 打开 **管理 → 定时和后台任务**。
2. 找到 **Mcp 代码检查** (`mcp_代码检查`) 任务。
3. 启用任务使用并配置时间表（推荐：每 **10–30 秒**）。
4. 确保 1C 服务器上可访问 `1cv8.exe`（用于构建 `.epf`）。
### 3. 发布 HTTP 服务
在 Web 服务器上发布 `mcp_APIBackend` HTTP 服务。
> **重要：** URL 中的数据库名称大小写必须 **完全** 匹配（例如 `base` 而不是 `Base`）。不匹配会导致重定向，这会将 POST 请求转换为 GET 请求。
URL 示例：`http://server/base/hs/mcp/`
### 4. 连接 AI 客户端
建议通过 [vladimir-kharin/1c_mcp](https://github.com/vladimir-kharin/1c_mcp) 中的 Python 代理连接：
```
AI 客户端 ←→ Python MCP 代理 ←→ 1C HTTP 服务
```
MCP 客户端配置示例在基础项目的 [mcp_client_settings](https://github.com/vladimir-kharin/1c_mcp/tree/main/mcp_client_settings) 目录中。
**Cursor 示例** (`~/.cursor/mcp.json`)：
```json
{
"mcpServers": {
"1c-server-direct": {
"url": "http://localhost:PORT/mcp",
"headers": {}
}
}
}
```
有关特定端口和代理启动方法的详细信息，请参阅基础项目中的 Python 代理文档。
## 安全性
`execute_1c_code_simple` 和 `execute_1c_code_complex` 工具 **执行任意代码**，在信息库上下文中。这是一个强大但潜在危险的机制。
**建议：**
- 不要在生产环境中未经身份验证发布 HTTP 服务。
- 使用带有 OAuth2 / 基本身份验证的 Python 代理。
- 将 MCP 访问权限限制在受信任的用户和开发环境中。
- 没有明确需求不要将生产数据库连接到 MCP。
## 自定义工具开发
1. 创建带有前缀 `mcp_工具名称` 的处理。
2. 将其包含在 `mcp_工具容器` 子系统中。
3. 在管理器模块中实现 `添加工具()` 和 `执行工具()` 方法。
详细指南请参阅 [agents.md](agents.md)。
## 致谢
该项目基于开源解决方案 [vladimir-kharin/1c_mcp](https://github.com/vladimir-kharin/1c_mcp)（MIT 许可证）。
## 许可证
MIT 许可证 - 请参阅 [LICENSE](LICENSE) 文件。
发布时请保留对 Vladimir Kharin 基础项目的作者署名。
