内容
# Efí MCP 服务器
Efí 的官方 MCP 服务器，通过 `stdio` 执行，提供 Efí 的 Model Context Protocol (MCP) API。公共合约来自 `sdk-node-apis-efi@2.0.0`；Efí 文档用于编写有用的描述，不会更改 SDK 的类型或验证。
这是 [该项目的官方仓库](https://github.com/efipay/mcp-server-efi)，也是 Efí 发布的所有软件包的来源。
## 覆盖范围
该目录涵盖 173 个方法。为安全起见，默认情况下会注册 170 个工具；三个返回证书、凭证或私钥的操作需要显式选择。
| API | HTTP 端点 | 本地操作 |
| ------------------- | ---------: | ---------: |
| 收费 | 47 | 0 |
| Pix | 78 | 2 |
| 开放金融 | 26 | 0 |
| 账户付款 | 7 | 0 |
| 账户开通 | 7 | 0 |
| 账户流水 | 6 | 0 |
工具名称使用 `snake_case`。输入仅在适用部分保留 `{ params, body }` 信封；兼容的开放金融突变也接受 `idempotency_key`。如果省略它，服务器会生成一个加密安全的密钥，并在成功或错误时返回，以允许有意识地重复相同的操作。
## 要求
- Node.js 22 或更高版本。
- Efí 应用程序的客户端 ID 和客户端密钥。
- 用于 mTLS API 的证书。只有 `cobrancas` 选区不需要证书。
## 凭证和 CLI 执行
凭证不会被接受为命令行参数，因为参数可能会出现在 shell 历史记录和进程列表中。创建一个本地 `.env.efi` 文件，将其排除在版本控制之外，并限制其读取权限：
```dotenv
EFI_CLIENT_ID=您的客户端 ID
EFI_CLIENT_SECRET=您的客户端密钥
EFI_SANDBOX=true
EFI_CERTIFICATE=/绝对路径/证书.p12
```
```bash
chmod 600 .env.efi
```
要使用 `npx` 执行软件包，请仅在进程环境中加载文件：
```bash
set -a
. ./.env.efi
set +a
npx -y mcp-server-efi --apis=pix,open-finance
```
如果没有 `--apis`，则启用六个域。接受的值为 `cobrancas`、`pix`、`open-finance`、`pagamento-contas`、`abertura-contas` 和 `extratos`。
## 配置
只有非机密选项才有标志。它们的优先级为 `CLI > EFI_* > 旧变量`：
| CLI | 环境变量 `EFI_*` | 旧变量 | 默认值 |
| ----------------- | ------------------- | --------------- | ----------- |
| `--sandbox` | `EFI_SANDBOX` | `SANDBOX` | 必需 |
| `--apis` | `EFI_APIS` | `APIS` | 所有 |
| `--cert-base64` | `EFI_CERT_BASE64` | `CERT_BASE64` | `true` |
| `--validate-mtls` | `EFI_VALIDATE_MTLS` | `VALIDATE_MTLS` | `true` |
| `--cache` | `EFI_CACHE` | `CACHE` | `true` |
| `-h`, `--help` | — | — | — |
布尔值接受 `true`、`false`、`1` 和 `0`。
mTLS 用于与接收兼容 webhook 的端点进行通信。`validate-mtls` 选项应保持为 `true` 以保持此保护；当设置为 `false` 时，SDK 仅在 webhook 配置期间发送验证绕过。出于安全考虑，我们不建议禁用它。
身份验证材料和敏感值仅通过以下变量接受，没有标志或前缀为 `EFI_` 的别名：
| 变量 | SDK 目标 | 必要性 |
| ------------------- | --------------- | ------------------------------------ |
| `EFI_CLIENT_ID` | `client_id` | 始终 |
| `EFI_CLIENT_SECRET` | `client_secret` | 始终 |
| `EFI_CERTIFICATE` | `certificate` | 当激活某个 mTLS API 时 |
| `EFI_PEM_KEY` | `pemKey` | 单独的 PEM 证书和密钥 |
| `EFI_PARTNER_TOKEN` | `partner_token` | 仅限兼容集成 |
没有全局幂等键：17 个开放金融突变中的每一个都接收显式调用密钥或新的 72 个字符的字母数字密钥。空值和 CR/LF 被拒绝。
### 敏感输出
这些工具默认不会出现在 `tools/list` 中：
- `create_account_certificate`
- `get_account_credentials`
- `create_sftp_key`
要仅启用必要的工具，请同时配置：
```dotenv
EFI_SENSITIVE_TOOLS=create_account_certificate,get_account_credentials
EFI_ACCEPT_SENSITIVE_OUTPUT_RISK=I_UNDERSTAND
```
不接受 `*`、`all`、别名、CLI 标志或在 MCP 调用中确认。不完整、未知或属于禁用 API 的选择将阻止初始化。
### 限制
进程立即拒绝过多的调用，而不创建队列或调用 SDK。结果使用 `isError: true`、`rate_limit_exceeded` 和 `retry_after_ms`。
| 变量 | 默认值 |
| ------------------------------- | -----: |
| `EFI_MAX_CONCURRENCY` | 4 |
| `EFI_MUTATION_MAX_CONCURRENCY` | 1 |
| `EFI_READ_RATE_PER_MINUTE` | 60 |
| `EFI_MUTATION_RATE_PER_MINUTE` | 10 |
| `EFI_SENSITIVE_RATE_PER_MINUTE` | 1 |
## 配置 MCP 主机
通常，启动 `stdio` 服务器的 MCP 客户端通过子进程的 `env` 字段提供凭证。这是 [MCP 本地服务器授权规范](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization) 的指南。根据客户端调整路径和值：
```json
{
"mcpServers": {
"mcp-server-efi": {
"command": "npx",
"args": [
"-y",
"mcp-server-efi",
"--sandbox=true",
"--apis=pix,open-finance",
"--cert-base64=false"
],
"env": {
"EFI_CLIENT_ID": "您的客户端 ID",
"EFI_CLIENT_SECRET": "您的客户端密钥",
"EFI_CERTIFICATE": "/绝对路径/证书.p12"
}
}
}
}
```
如果主机提供密钥库、安全保管或安全的机密替换，请优先使用此功能而不是配置文件中的字面值。存储库中的完整示例位于 [mcp.jsonc](mcp.jsonc) 中。
## Docker
镜像使用 Node 22、多阶段构建和非 root 进程。NPM、Corepack 和 Yarn 在安装后从最终层中删除：运行时包含 `node` 可执行文件和生产依赖项，但不包括包管理器。
```bash
docker pull ghcr.io/efipay/mcp-server-efi:1.0.0
docker run -i --rm \
--env-file .env.efi \
--mount type=bind,source=/绝对路径/证书.p12,target=/run/secrets/efi.p12,readonly \
--env EFI_CERTIFICATE=/run/secrets/efi.p12 \
ghcr.io/efipay/mcp-server-efi:1.0.0 \
--apis=pix,open-finance
```
绑定挂载使证书路径在容器内有效；它必须对 `node` 用户可读。作为替代方案，请在环境文件中将证书存储为 base64，并使用 `EFI_CERT_BASE64=true`，而无需挂载。
## 通过 Smithery 和 MCPB 安装
在 Smithery 安装过程中，服务器作为 MCP 包提供，并通过 `stdio` 在本地执行，而无需公共 URL。[MCPB 清单 0.3](manifest.json) 将凭证和证书标记为敏感配置，并通过 `EFI_*` 而不是 `args` 将它们路由到进程。
MCPB 安装程序默认仅选择 `cobrancas`。因此，它可以在没有 mTLS 证书的情况下启动；添加 Pix、开放金融、账户付款、账户开通或账户流水时，证书再次成为必需品。此默认设置与 CLI 不同：在没有 `--apis` 或 `EFI_APIS` 的情况下，CLI 启用六个域。
## MCP 合同和响应
- `params`、`body` 和响应使用 SDK 官方导出的 Zod 4 模式。
- JSON 响应作为文本和 `structuredContent.result` 提供。
- 没有内容的运算返回 `{ "success": true }`。
- Pix 凭证作为 PDF 资源公开；二维码可以包括图像内容。
- `pix_qr_code_detail` 保留通过与 SDK 中使用的相同解码器获得的 JWS，要求 `jku` 与访问的有效载荷具有相同的来源，并使用 JWKS 的 `kid` 验证签名。`invalid` 和 `unavailable` 状态是警报，不允许付款。
- Efí 的验证或失败返回 `isError: true`，并清理敏感数据。
- `stdout` 保留给协议；操作消息写入 `stderr`。
## 安全和更新
- 不接受任意的 HTTP 头。
- 不要在版本控制文件或日志中注册凭证、令牌、证书或 PEM 内容。
- 保持 `validate-mtls=true`；mTLS 保护兼容的 webhook 通信，出于安全考虑，我们不建议禁用它。
- 请参阅 [安全政策](SECURITY.md) 以报告漏洞。
- 迁移 0.x 版本之前，请参阅 [MIGRATION.md](MIGRATION.md)。
