内容
# cebelca-mcp
一款封装了 [cebelca.biz](https://www.cebelca.biz) 会计 API 的 MCP 服务器，使其能够被 MCP 客户端（如 Claude 等）调用。
## 开发
该项目使用 **[devenv](https://devenv.sh)** 作为其开发环境（Node.js，yarn）。安装 direnv 后，进入目录即可自动加载环境；否则运行 `devenv shell`。
cebelca.biz API 密钥从 **`CEBELCA_BIZ_API_KEY`** 环境变量中读取。它在 `.envrc`（git-ignored）中设置，由 direnv/devenv 加载。如果缺少该变量，服务器将拒绝启动。
可选：`CEBELCA_BIZ_BASE_URL` 可以覆盖 API 基本 URL（默认为 `https://www.cebelca.biz/API`）。
## 命令
```bash
yarn install # 安装依赖
yarn dev # 从源代码运行并使用 tsx（无需构建步骤）
yarn build # 将 TypeScript 编译到 dist/
yarn start # 运行编译后的服务器（dist/index.js）
yarn typecheck # 类型检查（不生成输出）
```
## 项目布局
```
src/
index.ts 入口点：构建服务器，通过 stdio 连接。
config.ts 从环境中加载配置（API 密钥，基本 URL）。
client.ts cebelca.biz 资源/方法 API 的 HTTP 客户端。
tools.ts MCP 工具注册。在此处添加新工具。
```
## cebelca.biz API
该 API 是一个资源/方法 RPC，基于 HTTP（文档：
[Workonomic-API-bash](https://github.com/InvoiceFox/Workonomic-API-bash/blob/master/API-docs.md),
[making-an-invoice](https://github.com/InvoiceFox/InvoiceFox-API-bash/blob/master/making-an-invoice.md)）：
- 每次调用都是一个 HTTP `POST`，带有 `x-www-form-urlencoded` 参数。
- 资源和方法分别放入 `_r` 和 `_m` 查询参数中（ `_m2` 堆叠第二个方法， `_f` 选择输出格式， `_x=1` 是探索模式）。
- 认证使用 HTTP Basic：API 令牌作为 **用户名**，密码为字面值 `x`。
- 成功响应类似于 `["ok", [{...}]]` 或 `[[{...}]]`；错误响应类似于 `["validation", {...}]` 或 `[[{"err": "..."}]]`。 `CebelcaClient` 解包成功负载，在失败时抛出 `CebelcaError`。
- PDF 文件来自单独的 `.../API-pdf` 端点。
## 工具
| 工具 | 用途 |
|------|---------|
| `cebelca_explore` | 发现资源/方法/参数（探索模式）。 |
| `cebelca_call` | 通用逃生口：直接调用任何资源/方法。 |
| `cebelca_assure_partner` | 查找或创建合作伙伴，返回其 ID。 |
| `cebelca_create_invoice_head` | 创建已发布的发票头（`insert-smart-2`）。 |
| `cebelca_add_invoice_line` | 向发票添加主体行。 |
| `cebelca_mark_invoice_paid` | 将发票标记为已支付（按 ID 或外部 ID）。 |
| `cebelca_finalize_invoice` | 发布发票 — `noncash` 或 `fiscal`（FURS）。 |
| `cebelca_get_fiscal_info` | 获取 ZOI/EOR/QR 财政详情。 |
| `cebelca_create_proforma_head` | 创建预发票头。 |
| `cebelca_add_proforma_line` | 向预发票添加主体行。 |
| `cebelca_proforma_to_invoice` | 将预发票转换为发票。 |
| `cebelca_get_pdf` | 获取文档 PDF 作为 base64 资源。 |
## 添加工具
在 `src/tools.ts` 中通过 `server.registerTool(...)` 注册新工具，使用 `CebelcaClient.call(resource, method, args)` 和 `run` 助手将响应（和 `CebelcaError`）转换为 MCP 工具结果。当需要一个操作时，没有专用工具涵盖，使用 `cebelca_explore` + `cebelca_call` 可以访问整个 API。
## 与 MCP 客户端一起使用
首先构建（`yarn build`），然后将客户端指向编译后的入口：
```json
{
"mcpServers": {
"cebelca": {
"command": "node",
"args": ["/absolute/path/to/cebelca-mcp/dist/index.js"],
"env": { "CEBELCA_BIZ_API_KEY": "your-key-here" }
}
}
}
```
