内容
# maxed-mcp
[](LICENSE)
一款 [模型上下文协议](https://modelcontextprotocol.io) 服务器，用于前端确定性工具，使 AI 代理能够以与调用其他 MCP 工具相同的方式调用它们。
代理擅长于判断，但不擅长于算术、解析和签名检查。该服务器将确定性、可审计的工作交给为其构建的库：解析银行对账单、分类文档、根据开放规范验证工作底稿、进行精确的货币数学运算、验证 webhook 签名。每个工具都返回结构化的 JSON 和统一的错误信封。这里没有任何生成式内容，也没有任何伪造内容：当后端工具未安装时，该工具会说明并告诉代理如何安装，而不是编造答案。
这是该套件的代理前端门户。解析器和验证器位于它们自己的仓库中，并保持其行为的单一真实来源；maxed-mcp 调用那些提供 CLI 的工具并解析它们的 JSON，并在进程中计算小的纯原始数据类型（货币数学、HMAC），镜像它们的规范 sibling 库的语义。
## 工具
| 工具 | 功能描述 | 后端 |
|---|---|---|
| `list_capabilities` | 列出每个工具及其后端是否已在此主机上安装。 | 进程内 |
| `normalize_bank_statement` | 将 CSV / OFX / QFX / MT940 / CAMT / QIF / 文本解析为规范的交易 JSON。 | [statement-normalizer](https://github.com/maxed-oss/statement-normalizer) CLI |
| `normalize_ofx` | 将 OFX/QFX 或 CSV 银行导出解析为规范的交易 JSON。 | [ofx-normalizer](https://github.com/maxed-oss/ofx-normalizer) `ofxnorm`（Go） |
| `classify_document` | 分类会计文档文本：`w2`、`form_1099`、`invoice`、`bank_statement`、`receipt` 或 `unknown`。 | [doc-classifier-kit](https://github.com/maxed-oss/doc-classifier-kit) CLI |
| `validate_workpaper` | 根据 [cpa-workpaper-spec](https://github.com/maxed-oss/cpa-workpaper-spec) JSON 模式验证文档。 | 模式验证器 |
| `money_allocate` | 按比率或均匀分配金额，无小数单位损失。 | [money-rs](https://github.com/maxed-oss/money-rs) 语义 |
| `money_apply_rate` | 应用费率（税、提示、份额）并显式舍入。 | [money-rs](https://github.com/maxed-oss/money-rs) 语义 |
| `verify_webhook_hmac` | 恒定时间验证 Stripe / hex / base64 webhook HMAC 签名。 | [webhook-hmac-verifier](https://github.com/maxed-oss/webhook-hmac-verifier) 语义 |
`money_*` 和 `verify_webhook_hmac` 在进程内计算，并始终可用；它们忠实地镜像 Rust 和 Go 库的规则，以便代理获得相同的答案。四个解析器和验证器工具调用 sibling CLI；首先调用 `list_capabilities` 以查看哪些工具已安装。
## 安装
```sh
pip install maxed-mcp
# 使两个 Python 支持的工具开箱即用：
pip install "maxed-mcp[suite]" # 添加 statement-normalizer + doc-classifier-kit
```
其余 shell 支持的工具的可选后端：
- `normalize_ofx`：构建 Go 二进制文件并将其放在 `PATH` 上（`go install github.com/maxed-oss/ofx-normalizer/cmd/ofxnorm@latest`）。
- `validate_workpaper`：将 `CPA_WORKPAPER_SPEC_DIR` 指向 `cpa-workpaper-spec` 的检出（包含 `validator/validate.py` 的目录）。
## 运行
```sh
maxed-mcp # 在标准输入/输出上启动服务器
python -m maxed_mcp # 等效
```
服务器通过标准输入/输出使用 MCP 进行通信，因此它可以与任何 MCP 客户端配合使用。像这样在客户端注册它（具体文件因客户端而异）：
```json
{
"mcpServers": {
"maxed": {
"command": "maxed-mcp",
"env": {
"CPA_WORKPAPER_SPEC_DIR": "/path/to/cpa-workpaper-spec"
}
}
}
}
```
## 后端解析
每个 shell 支持的工具按以下顺序解析其命令：
1. 显式环境变量（完整命令行）：`MAXED_MCP_STATEMENT_NORMALIZER`、`MAXED_MCP_DOC_CLASSIFIER`、`MAXED_MCP_OFXNORM`、`MAXED_MCP_CPA_WORKPAPER_VALIDATE`；
2. `PATH` 上的工具的控制台脚本（或 `ofxnorm` 二进制文件）；
3. 回退：`python -m ...` 用于 Python 工具，或用于验证器的 sibling `cpa-workpaper-spec/` 检出（`CPA_WORKPAPER_SPEC_DIR`）。
如果没有任何内容解析，该工具将返回 `{"ok": false, "error": {"code": "tool_unavailable", ...}}` 以及安装提示，而不是不透明地失败。
## 响应形状
每个工具都返回一个 JSON 对象。成功的结果包含 `"ok": true` 以及工具字段；失败的结果包含 `"ok": false` 和一个 `error` 对象：
```json
{ "ok": false, "error": { "code": "tool_unavailable", "message": "...", "detail": { "hint": "..." } } }
```
参见 [`AGENT.md`](AGENT.md) 以获取简化的机器接口，[`llms.txt`](llms.txt) 以获取机器可读的工具参考，[`examples/agent_call_example.py`](examples/agent_call_example.py) 以获取一个完整的、可运行的进程内客户端，该客户端调用每个工具。
## 开发
```sh
pip install -e ".[dev,suite]"
pytest -q
```
测试套件直接测试进程内工具，并针对已安装的 Python sibling 测试 shell 支持的工具；如果后端不存在，则断言温和的 `tool_unavailable` 路径。
## 许可证
Apache-2.0.
