Финансовый аналитик на базе MCP

Локальный AI-финансовый аналитик, построенный вокруг настоящего MCP-сервера (Model Context Protocol). Вместо одного чат-бота, который пытается угадать движения акций, работают два агента:

• Агент-валидатор — проверяет данные, полученные из интернета (Yahoo Finance, новостные API), на пропуски, некорректные значения или несоответствие тикеров до того, как что-либо попадёт в LLM.

• Агент-аналитик — рассуждает над проверенными данными и результатами MCP-инструментов, чтобы составить структурированную сводку (тренд, скользящие средние, волатильность и релевантные новостные настроения).

Оба агента вызывают инструменты, предоставляемые кастомным MCP-сервером — это ядро проекта, а не просто связующий код LangChain.

Что я добавил помимо базовой версии из туториала

• Разделение на двух агентов (Validator → Analyst) вместо одного агента, который делает всё

• Настоящий MCP-сервер с тремя инструментами, включая валидацию как отдельный инструмент

• Трассировка LangSmith на обоих агентах

• Кэширующий слой Neon Postgres (позволяет не обращаться повторно к API с лимитами)

• Небольшой набор eval-тестов с эталонными значениями, рассчитанными вручную

• Развёрнутое веб-приложение (FastAPI на Render, статический фронтенд на Vercel)

Related MCP server: AlphaVantage MCP Server

Архитектура

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); используется агентом-аналитиком и проверкой релевантности новостей

   • 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

   Обновите константу API_BASE_URL в верхней части index.html, чтобы она указывала на ваш бэкенд (http://localhost:8000 локально, ваш URL на Render после развёртывания).

6. Запуск набора eval-тестов

   python -m backend.evals.run_evals

Развёртывание (бесплатный уровень AWS)

Всё ниже укладывается в 12-месячный бесплатный уровень AWS (при условии, что вы выбираете указанные размеры инстансов из бесплатного уровня). Здесь не нужно менять код — то же FastAPI-приложение и MCP-сервер работают как есть.

1. База данных → RDS (Postgres)

1. AWS Console → RDS → Создать базу данных.

2. Движок: PostgreSQL. Шаблоны: Бесплатный уровень.

3. Класс инстанса: db.t3.micro (или db.t4g.micro — какой из них консоль предложит в качестве бесплатного уровня).

4. Задайте мастер-имя пользователя и пароль, сохраните их.

5. В разделе Connectivity выставьте Public access: Yes (это нужно, чтобы база была доступна с вашего EC2-инстанса и вашей собственной машины — для портфолио-проекта это нормально; позже можно ужесточить).

6. Когда база запустится, скопируйте endpoint (выглядит как xxxx.rds.amazonaws.com) и соберите строку подключения:

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

7. В Security Group инстанса RDS добавьте входящее правило: PostgreSQL (порт 5432), источник = ваш IP (для локального тестирования) и позже — security group вашего EC2-инстанса.

2. Бэкенд → EC2

1. AWS Console → EC2 → Запустить инстанс.

2. AMI: Amazon Linux 2023 (или Ubuntu 22.04). Тип инстанса: t2.micro (подходит для бесплатного уровня).

3. Создайте или скачайте пару ключей (файл .pem) — она нужна для подключения по SSH.

4. Security group: разрешите входящий SSH (порт 22, ваш IP) и пользовательский TCP-порт 8000 отовсюду (0.0.0.0/0), чтобы фронтенд мог обращаться к 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. Обновите API_BASE_URL в верхней части frontend/index.html, указав http://<your-ec2-public-ip>:8000.

2. С вашей собственной машины (с установленным AWS CLI и однократно выполненным aws configure с вашими учётными данными):

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

3. Скрипт создаёт bucket, включает статический хостинг сайта и загружает index.html. В конце он выводит ваш рабочий URL (http://<bucket>.s3-website-<region>.amazonaws.com).

4. Когда бы вы ни меняли фронтенд, просто запустите тот же скрипт заново, чтобы перезагрузить файлы.

Заметки

• Публичный IP EC2 меняется при остановке/запуске инстанса (если не прикрепить Elastic IP — он тоже бесплатен, пока прикреплён к запущенному инстансу). Если IP изменился, обновите API_BASE_URL и запустите скрипт развёртывания S3 заново.

• Чтобы расходы оставались нулевыми, придерживайтесь размеров бесплатного уровня t2.micro/db.t3.micro и помните, что бесплатный уровень AWS действует только первые 12 месяцев.

Будет ли это стоить денег на бесплатном уровне AWS?

Нет, если вы остаётесь в этих лимитах (всё это часть 12-месячного бесплатного уровня AWS для новых аккаунтов):

Что будет стоить денег, поэтому избегайте этого:

• Запуск второго EC2-инстанса или базы RDS одновременно (бесплатны только первые часы каждого сервиса — работа двух инстансов съедает двойные часы)

• Использование инстанса большего размера, чем t2.micro/t3.micro (EC2) или db.t3.micro/db.t4g.micro (RDS)

• Запрос Elastic IP и не прикрепление его к запущенному инстансу — AWS берёт плату за непривязанные Elastic IP именно чтобы это предотвратить

• Если ваш аккаунт AWS не новый — бесплатный уровень действует 12 месяцев с момента создания аккаунта; если аккаунт старше, эти сервисы будут тарифицироваться как обычно

Один предохранитель, который в любом случае стоит настроить: AWS Console → Billing → Budgets → создайте бюджетное оповещение на $1. Оно отправит вам письмо в тот момент, когда что-то начнёт стоить денег, так что сюрпризов не будет.

Заметки о MCP-слое

MCP-сервер (backend/mcp_server/server.py) — это отдельный процесс, который общается по протоколу Model Context Protocol через stdio. Агенты подключаются к нему как MCP-клиенты через langchain-mcp-adapters, который автоматически преобразует MCP-инструменты в совместимые с LangChain инструменты. Это значит, что тот же MCP-сервер можно подключить к Claude Desktop, Cursor или любому другому MCP-совместимому хосту без каких-либо изменений — в этом весь смысл такого подхода вместо захардкоженных схем инструментов внутри агента.