Financial Data MCP

金融数据MCP平台

隐私优先的金融情报平台，具有：

• MCP工具服务器
• Python编排API（通过LangGraph的单个附件软件聊天流）
• 单独的Next.js web应用程序

您可以通过两种方式使用此存储库：

• 作为一个 MCP 将金融工具直接暴露给MCP兼容客户端的服务器。
• 作为一个 LangGraph-通过API和UI接收PDF语句并回答自然语言问题的强大代理。

建筑

为什么这个项目存在

财务报表很难安全地与人工智能一起使用。该项目将PDF转换为经过净化的交易，并允许用户在不保留原始PII的情况下提出实用的预算问题。

重要的设计选择是，这两种运行时模式共享相同的核心金融工具和隐私优先的摄入管道。这意味着您可以：

• 直接通过MCP调用工具，或
• 使用高级代理体验，为您选择工具并起草答案。

特性

• 隐私优先的PDF摄取(ingest_financial_documents)
• 会话作用域内存事务状态（无跨用户混合）
• 综合洞察工具(financial_insights)
• 预算规划师实现节约目标和最大节约估算的能力(plan_savings)
• 用于前端应用程序的统一附件软件聊天API
• 货币、加密货币和股票工具
• MCP服务器和LangGraph代理使用的共享工具层

运行时模式

1.MCP服务器

当您希望其他AI客户端或MCP兼容的工具主机直接调用财务工具时，请使用MCP服务器。

此模式最适合：

• 直接调用工具
• 此仓库之外的工具组合
• 使用MCP的IDE或桌面助理集成

2.LangGraph代理

当您想要一个即用型会话工作流时，请使用LangGraph代理：

• 接受PDF上传
• 暂时摄取文件
• 决定调用哪些事务工具
• 从工具输出中起草可读的答案

此模式最适合：

• 聊天式财务分析
• PDF第一用户工作流
• 基于浏览器的演示或产品化的问答体验

核心工具

1. ingest_financial_documents
2. list_transactions
3. get_spending_summary
4. flag_anomalies
5. financial_insights
6. plan_savings
7. convert_currency
8. get_crypto_price
9. get_stock_quote

预算规划能力

确定性预算规划工具(plan_savings)在共享财务工具层中可用，现在通过MCP公开，并由LangGraph代理使用。

• 它按月份和类别分析摄入的历史借记交易。
• 它估计 max_savings_estimate 具有特定类别的切割天花板。
• 它评估了节约目标的可行性(target_met)当提供目标时。
• 它返回类别级别的建议和假设 supporting_data 用于代理/API使用。

示例提示：

• “这个月我怎么存300？”
• “这个月我最多能节省多少钱？”
• “积极计划储蓄，达到500美元的目标。”

笔记：

• 它首先需要摄入交易历史记录。
• 在MCP模式下，它使用与其他事务工具相同的默认内存事务会话。

仓库布局

• app/main.py -MCP注册+FastAPI应用程序引导
• app/api/orchestrator.py -会话+统一聊天API路由
• app/api/schemas.py -响应/请求合同
• app/agent/ -LangGraph状态、提示、节点、图形和运行器
• app/tools/ingestion.py -PDF提取+净化
• app/tools/transactions.py -对摄入的会话数据进行分析
• app/tools/insights.py -综合总结+异常解释
• ui/ -Next.js web应用程序
• tests/ -后端单元/API测试

快速入门

1） 共享设置

python -m venv .venv
source .venv/bin/activate
pip install -e ".[test]"
pytest

2） 创建一个真正的本地env文件

.env.example 只是一个模板。它不是由自动加载的 uvicorn，其中的值不会成为环境变量，除非您显式加载它们。

创建一个真正的本地 .env 文件优先：

cp .env.example .env

然后编辑 .env 并设置您真正的Anthropic密钥：

ANTHROPIC_API_KEY=your-real-key

如果你不提供 ANTHROPIC_API_KEY，LangGraph代理仍在运行，但计划和答案组合回归到确定性逻辑，而不是人择响应。

3） 运行MCP服务器

这将为MCP兼容客户端运行stdio MCP服务器：

python -m app.main

4） 运行LangGraph编排API

这将运行FastAPI应用程序，该应用程序为附件感知聊天流提供动力：

uvicorn app.main:app --reload

如果你想 uvicorn 从本地加载值 .env 文件自动，运行：

uvicorn app.main:app --env-file .env --reload

或使用：

make orchestrator-env

5） 运行前端

cd ui
npm install
npm run dev

前端默认URL: http://localhost:3000 后端默认URL: http://localhost:8000

这两个部分是如何结合在一起的

回购有两个主要的运行时界面，构建在相同的金融工具层之上：

• 这 MCP server 是直接工具表面。
• 这 LangGraph agent 是更高级别的编排层。
• 这两种模式都依赖于相同的摄取、净化和财务工具实现。

MCP服务器使用情况

MCP服务器直接公开共享财务工具，包括：

• ingest_financial_documents
• list_transactions
• get_spending_summary
• flag_anomalies
• financial_insights
• plan_savings
• convert_currency
• get_crypto_price
• get_stock_quote

典型MCP流程：

1. 呼叫 ingest_financial_documents 具有一个或多个PDF文件路径。
2. 调用交易工具，如 get_spending_summary, financial_insights，或 plan_savings.
3. 将加密货币、股票和货币工具视为低级市场工具。

编排API终结点

这 POST /api/chat 端点现在使用统一的事务优先LangGraph工作流：

• 阅读当前轮次的问题和附件参考文献
• 在图表中临时摄取上传的PDF
• 运行分析工具前需要事务上下文
• 使用Anthropic计划一个或多个事务工具（具有确定性本地回退）
• 迭代执行工具
• 写出可读的答案
• 隐私过滤最终答案和支持数据

POST /api/session

创建新的用户会话。

答复：

{"session_id":""}

GET /api/session/{session_id}/status

检查会话是否已摄入数据。

POST /api/chat

请求：

此端点接受多部分表单数据：

• session_id
• question （可选）
• files （可选，一个或多个PDF）

行为：

• 如果PDF毫无疑问地上传，代理会接收并返回 status: "needs_input" 并有后续提示。
• 如果还不存在交易数据，则代理返回 status: "needs_input" 并要求提供声明PDF。
• 如果存在交易数据，代理可以一次规划多个工具。

答复：

{
  "session_id":"",
  "status":"done",
  "answer":"Total spending is 1234.56 USD. Top categories are rent: 900.0 USD, food: 200.0 USD.",
  "tool_calls":["get_spending_summary"],
  "supporting_data":{
    "get_spending_summary": {
      "total_spend": 1234.56,
      "totals_by_category": {
        "rent": 900.0,
        "food": 200.0
      }
    }
  },
  "warnings":[],
  "missing_input": null
}

status 值：

• done -该回合以一个答案结束
• needs_input -代理人需要PDF或后续问题
• error -请求在内部失败

预算计划问题返回相同的响应模式，并在以下内容中包含计划员输出：

• tool_calls：包含 plan_savings
• supporting_data.plan_savings：确定性规划有效载荷（估计、建议、警告）

隐私保证

• 原始PDF文本是临时处理的，从不持久化。
• 仅保留经过净化的字段：日期、金额、商家、类别、货币、方向。
• 消毒可以删除长数字字符串、电子邮件和类似地址的模式。
• 日志避免原始文档内容。
• 每次上传后，上传的文件都会被删除 /api/chat 请求完成。

错误合同

{
  "ok": false,
  "error": "No ingested transactions available. Upload PDFs first.",
  "source": "orchestrator"
}

环境变量

• FRONTEND_ORIGINS （后端CORS，逗号分隔）
• ANTHROPIC_API_KEY （可选，启用Anthropic驱动的规划/组合；没有它，确定性回退仍然有效）
• LANGGRAPH_ANTHROPIC_MODEL （可选模型覆盖；默认 claude-3-5-sonnet-latest)
• LANGGRAPH_MAX_STEPS （可选编排步骤上限；默认值 4)
• NEXT_PUBLIC_ORCHESTRATOR_URL （前端API基础URL）

Docker Compose（3项服务）

docker compose up --build

服务：

• orchestrator-api 上 :8000
• ui 上 :3000
• mcp-server （标准化MCP流程）