基于 MCP 的金融分析师

一个本地优先的 AI 金融分析师，围绕一个真正的 MCP（Model Context Protocol）服务器构建。 不是由一个聊天机器人猜测股票走势，而是由两个代理协同工作：

• Validator agent（验证代理） — 在任何数据到达 LLM 之前，检查从互联网（Yahoo Finance、新闻 API）拉取的数据是否存在缺失、错误值或股票代码不匹配。

• Analyst agent（分析代理） — 基于已验证的数据和 MCP 工具输出进行推理，撰写结构化摘要（趋势、移动平均线、波动率和相关新闻情绪）。

两个代理都会调用由自定义 MCP server 暴露的工具——这是项目的核心，而不仅仅是 LangChain 胶水代码。

我在基础教程版本之外添加的内容

• 双代理拆分（Validator → Analyst），而不是由一个代理包办一切

• 一个真正的 MCP server，提供 3 个工具，其中验证是独立工具

• 两个代理上都启用了 LangSmith 跟踪

• Neon Postgres 缓存层（避免重复请求限流 API）

• 一套小型评估套件，带有手工计算的基准真值

• 已部署的 Web 应用（Render 上的 FastAPI，Vercel 上的静态前端）

Related MCP server: MonteWalk

架构

User query (ticker + date range)
        │
        ▼
  Validator agent ──calls──▶ MCP server ──▶ fetch_price_data (Yahoo Finance)
        │                                 ▶ validate_data
        │  (retries once on bad data)
        ▼
  Analyst agent ──calls──▶ MCP server ──▶ analyze_chart (moving averages, volatility)
        │                                ▶ get_news_sentiment
        ▼
  Structured summary + chart data → FastAPI → frontend

项目结构

backend/
  mcp_server/          # the MCP server + its 3 tools (this is the centerpiece)
  agents/               # Validator agent, Analyst agent
  orchestration/         # LangGraph wiring: Validator -> Analyst
  db/                    # Neon Postgres cache + eval result storage
  evals/                 # hand-checked test cases + eval runner
  main.py                # FastAPI app, deployed on Render
frontend/
  index.html             # single-page UI, deployed on Vercel
  vercel.json
render.yaml               # Render deployment config for the backend
requirements.txt
.env.example

设置

1. 克隆并安装

   git clone <your-repo-url>
   cd financial-analyst-mcp
   python -m venv venv && source venv/bin/activate
   pip install -r requirements.txt

2. 环境变量 — 将 .env.example 复制为 .env 并填写：

   • GROQ_API_KEY — 免费，无需付费（在 console.groq.com 注册），由 Analyst agent 和新闻相关性检查使用

   • DATABASE_URL — 你的 RDS Postgres 连接字符串

   • NEWSAPI_KEY — newsapi.org 的免费版（每天 100 次请求，无需信用卡）

   • LANGCHAIN_API_KEY、LANGCHAIN_PROJECT — 用于 LangSmith 跟踪（可选，免费版）

3. 创建数据库表

   python -m backend.db.database --init

4. 在本地运行后端

   uvicorn backend.main:app --reload --port 8000

5. 在本地运行前端 — 只需在浏览器中打开 frontend/index.html，或通过以下方式托管：

   cd frontend && python -m http.server 5500

   将 index.html 顶部的 API_BASE_URL 常量更新为指向你的后端（本地为 http://localhost:8000，部署后为你的 Render URL）。

6. 运行评估套件

   python -m backend.evals.run_evals

部署（AWS 免费套餐）

以下所有内容都保持在 AWS 12 个月免费套餐范围内（只要你选择文中所注明的免费套餐实例规格）。这里无需任何代码更改——同一个 FastAPI 应用和 MCP server 原样运行。

1. 数据库 → RDS（Postgres）

1. AWS 控制台 → RDS → 创建数据库。

2. 引擎：PostgreSQL。模板：免费套餐。

3. 实例类：db.t3.micro（或 db.t4g.micro，以控制台提供的免费套餐为准）。

4. 设置主用户名/密码，并记下来。

5. 在“连接”下，设置公共访问：是（这样你的 EC2 实例和你自己的机器才能访问它——对于作品集项目来说没问题；以后想收紧可以再改）。

6. 启动完成后，复制端点（看起来像 xxxx.rds.amazonaws.com）并构建你的连接字符串：

   DATABASE_URL=postgresql://<username>:<password>@<endpoint>:5432/postgres

7. 在 RDS 实例的安全组中，添加入站规则：PostgreSQL（端口 5432），来源 = 你的 IP（用于本地测试），之后再加上你的 EC2 实例的安全组。

2. 后端 → EC2

1. AWS 控制台 → EC2 → 启动实例。

2. AMI：Amazon Linux 2023（或 Ubuntu 22.04）。实例类型：t2.micro（符合免费套餐资格）。

3. 创建/下载密钥对（.pem 文件）——SSH 登录需要它。

4. 安全组：允许来自你的 IP 的入站 SSH（端口 22），以及来自任何位置（0.0.0.0/0）的自定义 TCP 端口 8000，以便前端可以访问 API。

5. 启动它，然后 SSH 登录：

   ssh -i your-key.pem ec2-user@<instance-public-ip>

6. 在实例上：

   git clone <your-repo-url> financial-analyst-mcp
   cd financial-analyst-mcp
   nano .env          # paste in GROQ_API_KEY (free, from console.groq.com), DATABASE_URL (from RDS), NEWSAPI_KEY, etc.
   bash aws/ec2-setup.sh

   这会安装 Python、依赖项，创建数据库表，并将后端作为 systemd 服务（financial-analyst）启动——即使你断开连接它也会持续运行，如果实例重启还会自动重启。

7. 确认它已启动：curl http://<instance-public-ip>:8000/health

3. 前端 → S3 静态网站

1. 将 frontend/index.html 顶部的 API_BASE_URL 更新为 http://<your-ec2-public-ip>:8000。

2. 从你自己的机器上（已安装 AWS CLI 并使用你的凭据运行过一次 aws configure）：

   BUCKET_NAME=your-unique-bucket-name bash aws/deploy-frontend-s3.sh

3. 该脚本会创建存储桶、开启静态网站托管并上传 index.html。它会在最后打印你的线上 URL（http://<bucket>.s3-website-<region>.amazonaws.com）。

4. 每当你更改前端，只需重新运行同一脚本即可重新上传。

说明

• 如果你停止/启动实例，EC2 的公有 IP 会变化（除非你绑定一个弹性 IP——只要它绑定在运行中的实例上，也是免费的）。如果你的 IP 变了，请更新 API_BASE_URL 并重新运行 S3 部署脚本。

• 要保持零成本，请坚持使用 t2.micro/db.t3.micro 免费套餐规格，并记住 AWS 免费套餐只覆盖你的前 12 个月。

这在 AWS 免费套餐上会产生费用吗？

不会，只要你保持在以下限制内（这些都属于新账户 AWS 12 个月免费套餐的一部分）：

会产生费用的事项，请避免：

• 同时启动第二个 EC2 实例或 RDS 数据库（每个服务只有首个免费套餐小时数是免费的——运行两个会消耗双倍小时数）

• 使用比 t2.micro/t3.micro（EC2）或 db.t3.micro/db.t4g.micro（RDS）更大的实例类型

• 申请弹性 IP 然后不将其绑定到运行中的实例——AWS 对未绑定的弹性 IP 收费正是为了阻止这种行为

• 如果你的 AWS 账户不是全新的——免费套餐是从账户创建起 12 个月，所以如果你使用账户超过这个时间，这些服务将正常计费

无论如何都值得设置的一个安全网： AWS 控制台 → Billing → Budgets → 创建一个 1 美元的预算提醒。一旦有任何东西开始产生费用，它会立刻发邮件通知你，这样你永远不会感到意外。

关于 MCP 层的说明

MCP server（backend/mcp_server/server.py）是一个独立进程，通过 stdio 使用 Model Context Protocol 进行通信。代理通过 langchain-mcp-adapters 以 MCP 客户端身份连接到它，该适配器会自动将 MCP 工具转换为与 LangChain 兼容的工具。这意味着同一个 MCP server 可以零改动地接入 Claude Desktop、Cursor 或任何其他兼容 MCP 的主机——这正是以这种方式构建，而不是把工具模式硬编码进代理的全部意义所在。