使用说明
发票数据库MCP服务器
MCP服务器公开发票数据库工具，供Cursor和其他MCP客户端使用。
设置
uv sync
数据库
服务器使用 SQLite （基于文件）。数据库文件是 db/invoices.db。首先通过运行以下命令创建架构 uv run python db/create_database.py （或用以下内容填充样本数据 db/populate_database.py，它需要一个现有的数据库）。
桌子：
| 表 | 目的 |
|---|---|
| 客户 | 客户记录： id, name, address, email, phone |
| 发票 | 每张发票一行： invoice_id, customer_id (→ 客户）， due_date, discount, tax, total_cost |
| 物品 | 每张发票的行项目： id, invoice_id (→ 发票）， name, description, price, quantity |
MCP工具
服务器注册了以下工具（名称是MCP客户端调用的）：
| 工具 | 参数 | 功能 |
|---|---|---|
| list_all_invoices | （无） | 以对象列表的形式返回每个发票 invoice_id, customer_id, due_date, discount, tax, total_cost，由 invoice_id。用于在客户端中扫描或过滤（例如逾期金额）。 |
| get_invoices_for_customer | customer_id （int） |
返回该客户的所有发票（与上述字段相同）。 |
| get_invoice_details | invoice_id （int） |
返回 { "invoice": ..., "items": [...] } 包含整行项目，或 null 如果发票不存在。 |
| get_customer_by_id | customer_id （int） |
返回客户字段(name, email, phone, address等等）或 {"error": "Customer … not found"}. |
| send_通知 | customer_id （int）， customer_name （str）， customer_email （str）， amount （浮动）， invoice_ids （str） |
记录逾期付款方式通知。将JSON对象附加到 notifications_sent.json 在项目根目录中并返回 {"status": "sent", ...}. invoice_ids 是一个以逗号分隔的发票ID列表，作为单个字符串 |
运行服务器
工作室 （默认值，用于光标）：
uv run python mcp_server.py
超文本传输协议 （适用于代理或远程客户端）：
uv run python mcp_server.py --http
# Listens at http://127.0.0.1:8000/mcp
# Options: --host, --port, --path
光标配置
选项A——标准 （需要时生成服务器）：
- 运输： 标准
- 命令：
uv run python mcp_server.py - 工作目录： 此项目的路径
选项B–HTTP （服务器必须先运行）：
- 运输： HTTP/URL
- 网址：
http://127.0.0.1:8000/mcp - 启动服务器：
uv run python mcp_server.py --http
逾期发票代理
发现超过1000美元的逾期发票并向客户发送通知的代理。使用LLM来决定 MCP工具 致电（通过 langchain-mcp-adapters).通过以下方式连接到MCP服务器 超文本传输协议.
使用的MCP工具 （见上表）： list_all_invoices （代理过滤逾期和金额）， get_customer_by_id, send_notification （附加到 notifications_sent.json).
模型： 开发和测试是通过 gpt-4o-mini （默认值为 agent.py 主要代理人和法官）。 提示7 （逾期发票按逾期天数分组--uv run python agent.py 7)更难：它需要正确的发票日期数学和分组。 gpt-4o-mini 可能会失败或得到不一致的判断结果 在这项任务上；使用一个 更强的推理模型 （例如。 o4-mini)如果您在生产中依赖提示7，请告知代理商和/或法官。
运行（2个终端）：
终端1–使用HTTP启动MCP服务器：
uv run python mcp_server.py --http
终端2–运行代理：
export OPENAI_API_KEY=your-key-here
uv run python agent.py
覆盖MCP URL： MCP_SERVER_URL=http://localhost:8000/mcp uv run python agent.py
测试
单元测试 （默认情况下，不需要API密钥）：
uv run pytest tests/ -v
集成测试 （真正的LLM，需要OPENAI_API_KEY和网络）：
OPENAI_API_KEY=your-key uv run pytest -m integration -v
