内容
# 辅助实验室-MCP财务核对
**MCP服务器用于月末结账核对**
财务共享服务 · GBS/SSC · 辅助比特
> 自动化共享服务团队中最手动、容易出错的活动：
银行核对、总账结账、公司间匹配和月末结账跟踪。
---
## 功能介绍
| MCP工具 | 描述 |
|---|---|
| `匹配银行对账单` | 匹配银行CSV与总账现金账簿 — ±3天日期接近，精确金额 |
| `核对总账科目` | 比较上一期与当前总账提取 — 新增条目、冲销、差异 |
| `检查公司间余额` | 实体A vs 实体B — 总体不匹配、外汇成分、风险标记 |
| `分类核对中断` | 基于规则的中断分类，推荐下一步操作 |
| `跟踪月末结账` | 12任务结账跟踪器，逾期检测和风险评级 |
---
## 快速入门
### 1. 安装
```bash
git clone https://github.com/auxiliobits/auxilab-mcp-finance-recon
cd auxilab-mcp-finance-recon
pip install -e ".[dev]"
```
### 2. 生成测试数据
```bash
python data/generate_test_data.py
```
这会创建`data/sample_data/`，包含7个合成CSV文件 — 无需真实数据。
### 3. 运行独立演示
```bash
python demo.py
```
预期输出：完整的5步核对流程，结束时生成月末准备报告。
### 4. 启动MCP服务器（用于Claude Desktop / 代理使用）
```bash
python src/server.py
```
---
## MCP服务器配置（claude_desktop_config.json）
```json
{
"mcpServers": {
"finance-recon": {
"command": "python",
"args": ["/path/to/auxilab-mcp-finance-recon/src/server.py"]
}
}
}
```
---
## 工具参考
### `匹配银行对账单`
```json
{
"bank_csv": "<CSV字符串>",
"gl_csv": "<CSV字符串>",
"opening_balance": 500000.00
}
```
**返回：** `reconciliation_summary`, `matched_pairs`, `unmatched_bank_items`, `unmatched_gl_items`
**匹配逻辑：**
- 金额匹配：精确到±$0.01
- 日期接近：±3日历天
- 决胜：使用描述的`token_sort_ratio`
---
### `核对总账科目`
```json
{
"period_a_csv": "<上一期CSV>",
"period_b_csv": "<当前期CSV>",
"account_name": "Accrued Liabilities — 2110"
}
```
**返回：** `reconciliation_statement`, `new_entries`, `removed_entries`, `reversals`, `common_entries`
---
### `检查公司间余额`
```json
{
"entity_a_csv": "<实体A总账CSV>",
"entity_b_csv": "<实体B总账CSV>",
"entity_a_name": "Auxiliobits India",
"entity_b_name": "Auxiliobits Singapore",
"base_currency": "USD"
}
```
**返回：** `summary` （包含 `mismatch_risk`：NONE/LOW/MEDIUM/HIGH/CRITICAL），`matched_transactions`，实体专有列表，`mismatch_detail`
**演示场景：** 实体A = $125,000应收 · 实体B = $123,500应付 → $1,500不匹配，标记为HIGH
---
### `分类核对中断`
```json
{
"breaks_csv": "<未核对项目CSV>"
}
```
CSV列：`reference, date, description, amount, source`
**分类类别：**
| 类别 | 规则 |
|---|---|
| 时间差异 | 关键词：transit, outstanding, cut-off, clearing |
| 缺失条目 | 关键词：missing, not posted, unposted |
| 重复记账 | 关键词：duplicate, double post, twice |
| 货币四舍五入 | 金额≤$10，或包含FX/forex关键词 |
| 公司间不匹配 | 关键词：interco, entity, subsidiary |
| 未知 | 无匹配规则 — 升级 |
---
### `跟踪月末结账`
```json
{
"tasks_csv": "<任务CSV>",
"close_deadline": "2024-11-30",
"as_of_date": "2024-11-29"
}
```
CSV列：`account_name, owner, status, due_date`
有效状态：`complete`, `in progress`, `not started`, `overdue`, `on hold`
**风险逻辑：**
- `CRITICAL`：截止日期≤1天且有未完成任务，或截止日期已过
- `HIGH`：截止日期≤2天且有>3个未完成任务，或≥3个逾期任务
- `MEDIUM`：完成度<75%或有逾期任务
- `LOW`：按计划进行
---
## 项目结构
```
auxilab-mcp-finance-recon/
├── src/
│ ├── server.py # MCP服务器 — 工具注册 + 调度
│ └── tools/
│ ├── __init__.py
│ ├── bank_matcher.py # 银行 ↔ 总账匹配（Pandas + rapidfuzz）
│ ├── gl_reconciler.py # 上一期 vs 当前期总账提取差异
│ ├── intercompany_checker.py # 实体A vs 实体B
│ ├── break_classifier.py # 基于规则的中断分类器
│ └── close_tracker.py # 月末任务跟踪器
├── data/
│ ├── generate_test_data.py # 合成CSV生成器
│ └── sample_data/ # 生成的CSV（gitignored）
├── tests/
│ └── test_tools.py
├── demo.py # 完整5步演示运行器
├── pyproject.toml
└── README.md
```
---
## 技术栈
| 组件 | 库 |
|---|---|
| MCP协议 | `mcp` Python SDK >= 1.0.0 |
| 匹配逻辑 | `pandas` >= 2.0, `numpy` |
| 模糊描述匹配 | `rapidfuzz` （备用`difflib`）|
| CSV解析 | `pandas.read_csv` |
| 中断分类 | 基于规则（正则表达式）— 无LLM需求 |
---
## 演示数据摘要
| 文件 | 行数 | 备注 |
|---|---|---|
| `bank_statement.csv` | 50 | 独特金额，整月 |
| `gl_cash_ledger.csv` | 48 | 45匹配银行（±1-2天漂移），3个总账专有时间项目 |
| `gl_prior_period.csv` | 20 | 10月总账提取 |
| `gl_current_period.csv` | 25 | 15个结转 + 8个新增 + 2个冲销 |
| `entity_a_ledger.csv` | 3 | $125,000应收 |
| `entity_b_ledger.csv` | 3 | $123,500应付 — $1,500不匹配 |
| `month_end_tasks.csv` | 12 | 4个完成，3个逾期，截止日期1天 → HIGH风险 |
| `breaks_sample.csv` | 8 | 涵盖所有6个中断类别 |
---
## 许可证
MIT · 为Auxiliobits黑客马拉松 — 财务核对支柱而建
