内容
# 财务账单智能汇总 — Skill & MCP
面试作业：MCP Server + Skill，让 Cursor / Claude Code / Codex 的 Agent 自动汇总账单并推送报告。
## 项目结构
```
mcpskill/
├── mcp-server/
│ ├── server.py # MCP 入口，注册 5 个 Tool
│ ├── bill_io.py # Tool 1/2 ✅ 已实现
│ ├── parsers.py # Tool 3 ✅ 已实现
│ ├── report.py # Tool 4 ✅ 已实现
│ ├── notify.py # Tool 5 ✅ 已实现
│ ├── requirements.txt
│ └── scripts/
│ └── smoke_test.py # 本地验证 Tool 1/2
├── sample_data/ # 3 种格式示例账单
├── .cursor/
│ ├── mcp.json # Cursor MCP 配置
│ └── skills/
│ └── finance-bill-summary/
│ ├── SKILL.md # Agent 操作手册
│ └── reference.md # Tool schema（渐进式披露）
├── configs/ # Claude Code / Codex 配置
└── docs/
└── IMPLEMENTATION.md # 逐步实现指南 ← 从这里开始
```
## 快速开始（Conda，推荐）
本项目使用 conda 环境 **`mcpskill`**（Python 3.12）。
```bash
# 1. 创建并激活环境（首次）
conda env create -f environment.yml
conda activate mcpskill
# 若环境已存在，只需激活
conda activate mcpskill
# 2. 验证 Tool 1/2
python mcp-server/scripts/smoke_test.py
# 3. 配置飞书 Webhook（可选）
# 编辑 .cursor/mcp.json 中的 FEISHU_WEBHOOK_URL
# 4. 在 Cursor 中启用 MCP
# Settings → MCP → 确认 finance-bill 为绿灯（需 Reload 一次）
```
**Python 解释器路径**（Cursor / VS Code 已写入 `.vscode/settings.json`）：
```
D:\miniconda3\envs\mcpskill\python.exe
```
**PyCharm 用户**：File → Settings → Project → Python Interpreter → 选上述路径即可。
## 快速开始（venv，备选）
```bash
python -m venv .venv
.venv\Scripts\activate
pip install -r mcp-server/requirements.txt
python mcp-server/scripts/smoke_test.py
```
## MCP 配置说明
`.cursor/mcp.json` 中：
```json
{
"command": "python",
"args": ["mcp-server/server.py"]
}
```
`args` 指向 MCP Server 入口，等价于终端执行 `python mcp-server/server.py`。
若使用虚拟环境，把 `command` 改为 `.venv/Scripts/python.exe` 的绝对路径。
## 实现进度
| Tool | 状态 | 文件 |
|------|------|------|
| list_directory | ✅ | bill_io.py |
| read_bill_file | ✅ | bill_io.py |
| parse_and_clean_bills | ✅ | parsers.py |
| generate_report | ✅ | report.py |
| send_notification | ✅ | notify.py |
详细步骤见 [docs/IMPLEMENTATION.md](docs/IMPLEMENTATION.md)。
- [√] MCP Server 可正常启动
- [√] 5 个核心 Tool 均可被 AI Agent 正确调用并返回预期结果
- [√] Skill 文件格式规范，可供 Cursor / Claude Code / Codex 加载用于演示
- [√] `sample_data/` 包含 ≥3 个不同格式的 `.md` 账单文件
- [√] 端到端演示：从读取目录到发送通知，全流程跑通
## 设计决策（面试参考）
- **MCP 做工具，Skill 做编排**：Skill 告诉 Agent 何时、按何顺序调用 Tool
- **Tool 粒度**：读、解析、汇总、发送分离，单文件失败不影响全局
- **parse 不调 LLM**：确定性解析，Agent 负责编排而非在 Tool 内推理
## License
MIT
