MCP Server - 自建应用

一.项目说明

本项目是基于 MCP (Model Context Protocol) 的腾讯电子签 API 服务网关，能够将腾讯电子签 API 接口注册为 MCP 工具，供大模型（如 Claude、GPT 等）直接调用。

效果演示视频：点击查看使用效果

通过 MCP Server，您可以在支持 MCP 协议的 AI 客户端中，用自然语言完成电子签的各项操作，例如：

查询模板列表
通过文件或模板发起合同
查询合同详情
获取签署链接
管理企业员工、部门、印章等

并不是所有的接口都默认加载，开发者可以在 `config.yaml` 中按照自己的开发需求配置需要加载的 API 接口白名单。

二.环境要求

Go 1.23.0 或更高版本（用于编译）
支持 MCP 协议的 AI 客户端（如 Claude Desktop、Cursor、Cline 等）

三.编译与部署

1.下载预编译包（推荐）

您可以直接前往 GitHub Releases 页面，根据您的操作系统和 CPU 架构选择对应的安装包下载，无需自行编译。

操作系统	CPU 架构	安装包名称
Windows	x86_64 (AMD64)	`ess_mcp_server_windows_amd64.zip`
Windows	ARM64	`ess_mcp_server_windows_arm64.zip`
macOS	Intel (AMD64)	`ess_mcp_server_darwin_amd64.tar.gz`
macOS	Apple Silicon (ARM64)	`ess_mcp_server_darwin_arm64.tar.gz`
Linux	x86_64 (AMD64)	`ess_mcp_server_linux_amd64.tar.gz`
Linux	ARM64	`ess_mcp_server_linux_arm64.tar.gz`

下载后解压即可使用，压缩包内已包含可执行文件和所需的配置文件。

2.从源码编译

如果您需要从源码编译，请确保已安装 Go 1.23.0 或更高版本，然后执行以下步骤：

git clone https://github.com/tencentess/ess_mcp_server
cd ess_mcp_server
go mod tidy
go build

编译完成后会在当前目录生成 ess_mcp_server 可执行文件。

3.部署结构

请确保以下文件在同一目录下：

├── ess_mcp_server       # 可执行文件
├── config.yaml          # 配置文件
└── yaml/                # Swagger API 定义文件目录
    ├── ess_1.yaml       # 自建应用集成接口定义
    └── ess_2.yaml       # 自建应用集成接口定义（续）

4.启动服务

./ess_mcp_server

启动成功后，MCP Server 将监听配置文件中指定的端口（默认 8080），日志文件位于 ./log/ 目录下。

四.配置文件说明

配置文件为可执行文件同目录下的 config.yaml，主要包含以下几个部分：

1.服务配置

server:
  # MCP Server 对外可访问的 IP 或域名（不含协议和端口）
  # 用于与 port 组合生成文件上传服务地址（http://{server_ip}:{port}）
  # 部署到远程服务器时需改为实际 IP 或域名，默认值为 localhost
  server_ip: 'localhost'
  # MCP Server 监听端口（默认 8080）
  port: '8080'
  # MCP Server 名称
  name: '腾讯电子签 ESS MCP Server'
  # MCP Server 版本
  version: '1.0.0'
  # 是否开启 debug 模式（开启后会打印请求参数、响应内容等详细日志）
  debug: true

配置项	说明
`server_ip`	服务对外可访问的 IP 或域名（不含协议和端口），用于与 `port` 组合生成文件上传服务地址（`http://{server_ip}:{port}`）。默认 `localhost`，部署到远程服务器时需改为实际 IP 或域名
`port`	服务监听端口，默认 `8080`
`debug`	是否开启 debug 模式，开启后会在日志中打印请求参数和响应内容

2.凭证配置

credentials:
  # 腾讯云 SecretId
  secret_id: '你的 SecretId'
  # 腾讯云 SecretKey
  secret_key: '你的 SecretKey'
  # 环境（可选值: test / online）
  env: 'test'
  # 默认操作人 UserId
  # 如果配置了此项，API 调用时会自动注入到 Operator.UserId 中（不覆盖用户显式传递的值）
  # 也可通过 HTTP Header X-User-Id 覆盖
  user_id: ''

可以参考获取密钥 SecretId 和 SecretKey（联调环境）获取 SecretId 和 SecretKey。

配置项	说明
`secret_id`	腾讯云 SecretId
`secret_key`	腾讯云 SecretKey
`env`	环境，可选值：`test`（联调环境） / `online`（正式环境）
`user_id`	默认操作人 UserId。配置后 API 调用时会自动注入到 `Operator.UserId` 参数中，不会覆盖用户显式传递的值。也可通过 HTTP Header `X-User-Id` 覆盖

注意：凭证也可以通过 MCP Client 的 HTTP Headers 传递，Header 中的凭证优先级高于配置文件。

3.API 接口白名单

api:
  # 腾讯云 API 服务名（ess 为自建应用集成，essbasic 为第三方应用集成）
  service: 'ess'
  # 需要加载的 API 接口白名单
  loading_apis:
    - DescribeFlowTemplates
    - CreateFlowByFiles
    - DescribeFlowInfo
    # ... 按需添加

建议按需配置 API 白名单，接口太多不仅导致 token 消耗过快，还可能导致 MCP Client 报 too large 错误。

4.描述截断配置

schema:
  # 工具列表中精简描述的最大长度（默认 300）
  desc_max_len_short: 300
  # 接口详情描述的最大长度（默认 400）
  desc_max_len_long: 400
  # 每个参数描述的最大长度（默认 150）
  desc_max_len_medium: 150
  # 参数详细说明最大递归深度（默认 4）
  schema_max_detail_depth: 4

这些配置用于平衡接口描述的准确度与 token 消耗，可根据实际使用情况调整。

五.MCP Client 接入

1.基础接入

在您的 MCP Client 配置中添加以下内容：

{
  "mcpServers": {
    "ess": {
      "url": "http://你部署服务的地址:8080/mcp"
    }
  }
}

此方式将使用 config.yaml 中配置的默认凭证。

2.通过 HTTP Headers 传递凭证

如果需要每个 MCP Client 使用各自的凭证，可以在连接配置中通过 Headers 传递：

{
  "mcpServers": {
    "ess": {
      "url": "http://你部署服务的地址:8080/mcp",
      "headers": {
        "X-Secret-Id": "你的腾讯云 SecretId",
        "X-Secret-Key": "你的腾讯云 SecretKey",
        "X-Env": "test",
        "X-User-Id": "操作人员的UserId"
      }
    }
  }
}

Header	说明
`X-Secret-Id`	腾讯云 SecretId
`X-Secret-Key`	腾讯云 SecretKey
`X-Env`	环境，可选值：`test`（联调环境） / `online`（正式环境）
`X-User-Id`	操作人 UserId，覆盖 `config.yaml` 中的 `credentials.user_id`

请求时 Headers 中的凭证优先级高于 config.yaml 中的默认配置。

六.使用示例

示例 1：上传文件

在 MCP Client 中用自然语言提问：

    帮我上传一个文件，文件地址是 https://qcloudimg.tencent-cloud.cn/raw/4221137b4fad7ac4b60f8ab96961b81a.pdf，操作员的 UserId 为 yDwfGUUwmf6fxUxZPmtb8PAfVVCrB03E

大模型将自动调用 UploadFiles 接口完成文件上传，并返回文件资源 ID（FileId），用于后续创建合同。

示例 2：创建合同

    帮我用 PDF 文件创建一个签署流程，合同名称为 mcp 测试合同，使用已上传的文件资源 ID yD3a1UUqi3mg89USyGa1wheheFqA8MR8，签署方是张三（手机号 18500000000），让他在'乙方（买方）签字'位置签个名字

大模型将自动编排参数并调用 CreateFlowByFiles 接口完成合同发起，通过关键字定位方式将签名控件放置到 PDF 中指定位置。

示例 3：生成签署链接

    帮我生成合同 yD3a1UUqivpvhwUEnTiJbSKhT6DjmbLe 中刘波的小程序签署链接

大模型将调用 CreateSchemeUrl 接口生成跳转至腾讯电子签小程序的签署短链接和二维码，签署人可通过手机浏览器打开或扫码签署。

示例 4：拉取合同信息

    帮我查询合同流程 ID 为 yD3a1UUqivpvhwUEnTiJbSKhT6DjmbLe 的详细信息

大模型将自动调用 DescribeFlowInfo 接口查询合同的详细信息，包括合同状态、签署方信息、签署进度等。

示例 5：生成出证报告

    帮我为合同 yD3a1UUqivpvhwUEnTiJbSKhT6DjmbLe 申请出证报告

大模型将调用 CreateFlowEvidenceReport 接口提交出证报告申请任务，返回报告 ID。之后可通过 DescribeFlowEvidenceReport 接口查询报告生成状态和下载链接。

七.常见问题

1. MCP Client 报 "too large" 错误

原因：加载的 API 接口过多，导致工具描述信息超出 MCP Client 的 token 限制。

解决方案：

在 config.yaml 的 loading_apis 中只配置实际需要的接口
适当降低 schema.desc_max_len_short 和 schema.schema_max_detail_depth 的值

2. 接口调用返回鉴权失败

原因：SecretId 或 SecretKey 配置错误，或使用了错误的环境。

解决方案：

检查 config.yaml 中的 credentials 配置或 MCP Client Headers 中的凭证是否正确
确认 env 值与实际使用的环境一致（test 为联调环境，online 为正式环境）

3. 日志在哪里查看

日志文件位于可执行文件同目录的 ./log/ 目录下，文件名为 <主机名>.log。开启 debug: true 后可查看详细的请求参数和响应内容。

一.项目说明​

二.环境要求​

三.编译与部署​

1.下载预编译包（推荐）​

2.从源码编译​

3.部署结构​

4.启动服务​

四.配置文件说明​

1.服务配置​

2.凭证配置​

3.API 接口白名单​

4.描述截断配置​

五.MCP Client 接入​

1.基础接入​

2.通过 HTTP Headers 传递凭证​

六.使用示例​

示例 1：上传文件​

示例 2：创建合同​

示例 3：生成签署链接​

示例 4：拉取合同信息​

示例 5：生成出证报告​

七.常见问题​

1. MCP Client 报 "too large" 错误​

2. 接口调用返回鉴权失败​

3. 日志在哪里查看​