Финансовый AI-Агент на Python: MCP и CodeAct

Интеллектуальный AI-ассистент для трейдинга, который превращает естественный язык в реальные действия на бирже. Проект демонстрирует архитектуру CodeAct — когда AI пишет и выполняет Python-код вместо прямых вызовов функций, решая проблему переполнения контекстного окна при работе с большими объемами данных.

📖 О проекте

Это практическая реализация идей из серии статей о создании финансового AI-ассистента:

Создание MCP-сервера для Finam API — построение MCP-сервера с инструментами для работы с биржей
Подключение MCP к Claude Desktop — интеграция без кода
Финансовый AI-агент: MCP и CodeAct — эта статья, описывающая данный проект

Проблема классического подхода

Обычный MCP-агент передает все инструменты в контекст модели сразу. При запросе списка из 8500 финансовых инструментов получаем:

580 000 токенов в контекстном окне
Превышение лимита большинства моделей (Claude 200k, GPT-5.1 1M)
Высокая стоимость обработки
Низкая эффективность

Решение: CodeAct архитектура

Вместо прямой передачи инструментов LLM, создаем Python API-обертку над MCP. AI пишет код, который:

Постепенно раскрывает возможности — загружает только нужные API по требованию
Эффективно обрабатывает данные — фильтрует 8500 инструментов до топ-10 без переполнения контекста
Гибко управляет потоком — использует циклы, условия, async/await, обработку ошибок
Сохраняет состояние — переменные и функции между вызовами (как в Jupyter)

🎯 Возможности

Что умеет ассистент

Покажи мне топ-10 финансовых акций по росту за месяц с объёмом от 50 млн рублей

Ассистент самостоятельно:

Использует list_tool() для обнаружения доступных API
Вызывает read_tool() для изучения интерфейса нужных инструментов
Пишет Python-код с вызовами MCP через API-обертку
Выполняет код в безопасной песочнице
Фильтрует и анализирует тысячи инструментов
Создает интерактивные Plotly визуализации
Выдает рекомендации

Практические кейсы

🗂️ Портфельный аналитик

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

🔍 Рыночный сканер

Найди все акции на Мосбирже из финансового сектора, которые выросли более чем на 5% за неделю при объеме торгов выше 500 млн рублей.

📊 Техническая аналитика

Построй свечной график SBER@MISX за последний месяц с индикаторами RSI и MACD

🧪 Бэктестинг стратегий

Проверь стратегию арбитража между фьючерсами Сбер и Сбер-преф за последние 3 месяца

🏗️ Архитектура

Проект состоит из двух компонентов:

1. MCP Server (finam-mcp)

FastMCP сервер, предоставляющий инструменты для работы с Finam TradeAPI.

Репозиторий: https://github.com/Alexander-Panov/finam-mcp

Важно: finam-mcp включен как git submodule в этот проект, поэтому клонируется автоматически вместе с основным репозиторием.

2. AI Assistant (CodeAct Agent)

┌─────────────────────────────────────────────────────────────┐
│                        User Request                         │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                     LangGraph Agent                         │
│  ┌─────────────────────────────────────────────────────┐   │
│  │  1. list_tool()  → Discover available APIs          │   │
│  │  2. read_tool()  → Learn interface                  │   │
│  │  3. run_python_code() → Write & execute code        │   │
│  └─────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                    Python Sandbox                           │
│  ┌─────────────────────────────────────────────────────┐   │
│  │  Generated Code:                                    │   │
│  │  from finam.assets import get_assets                │   │
│  │  from finam.market_data import get_bars             │   │
│  │                                                      │   │
│  │  assets = get_assets()  # → mcp.call_tool()        │   │
│  │  filtered = [a for a in assets if ...]             │   │
│  │  return plotly_chart                                │   │
│  └─────────────────────────────────────────────────────┘   │
│                              │                              │
│                         MCP Binding                         │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                       MCP Server                            │
│                    (Finam TradeAPI)                         │
└─────────────────────────────────────────────────────────────┘

Ключевые компоненты

1. Генерация API-обертки (src/ai/mcp_client/utils.py)

Автоматическое создание Python модулей из MCP инструментов
Pydantic модели для входа/выхода
Docstrings для документации

# mcpServers/finam/assets/get_asset.py (сгенерировано автоматически)
def get_asset(symbol: str) -> AssetsGetOutput:
    """Получение информации по конкретному инструменту"""
    return AssetsGetOutput.model_validate(
        mcp.call_tool("assets_get_asset", symbol=symbol)
    )

2. MCP Binding (src/ai/mcp_client/mcp_client.py)

Связь между Python sandbox и MCP сервером
Доступен в коде как глобальная переменная mcp
Передача Finam credentials через HTTP заголовки

3. Python Sandbox (src/ai/tools/code_executor.py)

Выполнение кода через exec() с сохранением состояния
Автоматическое извлечение return value (как в Jupyter)
Захват stdout/stderr
Сериализация Plotly/DataFrame для UI

4. Tools для агента (src/ai/tools/)

list_tool(path) — список доступных API с кратким описанием
read_tool(tool_name) — полная документация (код + Pydantic схемы)
run_python_code(code) — выполнение Python кода

5. LangGraph граф (src/ai/graph.py)

Узел model — вызов LLM (Claude, GPT, Gemini)
Узел tools — выполнение инструментов
Checkpointing через SQLite для сохранения истории

🔄 MCP-агент vs CodeAct-агент

	MCP-агент	CodeAct-агент
Суть	Инструменты напрямую вызываются агентом	Инструменты вызываются через написанный агентом код
Сложность	Легкая реализация	Продвинутая реализация
Токены	Все инструменты в контексте сразу	Постепенное раскрытие по требованию
Обработка ошибок	Нет	Есть (try/except, условия, циклы)
Параллелизм	Последовательное выполнение	Возможен async/await
Большие данные	Переполнение контекста	Эффективная фильтрация в коде
Подходит для	Простые интеграции, мало инструментов	Сложные воркфлоу, большие данные

🚀 Быстрый старт

Требования

Python 3.12+
uv (менеджер пакетов)
Git

Установка

Клонируйте репозиторий с submodules:

git clone --recurse-submodules https://github.com/Alexander-Panov/fin-ai-agent.git
cd fin-ai-agent

Если уже склонировали без --recurse-submodules, инициализируйте submodule:

git submodule update --init --recursive

Настройте переменные окружения:

Создайте .env файл:

# Finam API (получить в личном кабинете)
FINAM_API_KEY=your_api_key
FINAM_ACCOUNT_ID=your_account_id

# MCP Server
MCP_SERVER_URL=http://127.0.0.1:3000

# LLM API Keys (openrouter)
OPENROUTER_API_KEY=

Установите зависимости:

uv sync              # Основные зависимости
uv sync --group dev  # С dev-зависимостями (тесты)

Запуск

Терминал 1 — MCP Server:

# Перейдите в директорию MCP сервера (git submodule)
cd finam-mcp
$env:PYTHONPATH="." ; fastmcp run src/main.py:create_server

MCP сервер запустится на http://127.0.0.1:3000

Терминал 2 — AI Assistant:

cd fin-ai-agent
streamlit run src/app.py

Откройте браузер: http://localhost:8501

Генерация API-обертки

При первом запуске автоматически создастся директория mcpServers/ с Python модулями. Для ручной регенерации:

from src.ai.mcp_client.utils import generate_mcp_files
generate_mcp_files()

💻 Примеры использования

Базовые запросы

Какая цена Сбербанка?

Покажи мой портфель с текущей стоимостью позиций

Что в стакане по GAZP@MISX?

Аналитика

Построй корреляционную матрицу между SBER, GAZP, LKOH за последние 3 месяца

Найди все акции с RSI < 30 (перепроданность) и объемом > 100M

Визуализация

Покажи свечной график YNDX@MISX с объемами за последний месяц

Построй heatmap секторального распределения моего портфеля

🧪 Тестирование

# Запуск всех тестов
pytest

# Конкретный файл
pytest tests/test_code_executor.py

# С подробным выводом
pytest -v

# Важно: используйте python -m pytest вместо просто pytest
python -m pytest

🛠️ Технологии

Core

Python 3.12 — основной язык
FastMCP — MCP сервер (отдельный репозиторий)
LangGraph — фреймворк для AI-агентов
LangChain — интеграция с LLM
Pydantic — валидация данных и схемы

UI & Visualization

Streamlit — веб-интерфейс
Plotly — интерактивные графики
Pandas — обработка данных

Infrastructure

uv — менеджер пакетов и виртуальных окружений
SQLite — хранение истории сессий (через AsyncSqliteSaver)

LLM Providers

OpenAI (GPT-4o, GPT-5, o1, o3-mini)
Google (Gemini 2.5 Pro/Flash, Gemini 2.0 Flash)
Anthropic (Claude 4 Opus/Sonnet, Claude 3.7 Sonnet)

📁 Структура проекта

fin-ai-agent/
├── src/
│   ├── ai/
│   │   ├── graph.py              # LangGraph граф (model + tools)
│   │   ├── prompt.py             # Системный промпт
│   │   ├── state.py              # AgentState
│   │   ├── tools/
│   │   │   ├── code_executor.py  # Python sandbox (exec)
│   │   │   ├── mcp_tools.py      # list_tool, read_tool
│   │   │   └── utils.py          # Сериализация outputs
│   │   └── mcp_client/
│   │       ├── mcp_client.py     # MCPBinding класс
│   │       └── utils.py          # generate_mcp_files
│   ├── ui/
│   │   ├── chats.py              # Управление сессиями (SQLite)
│   │   └── utils.py              # UI helpers
│   ├── app.py                    # Главный Streamlit файл
│   ├── config.py                 # Настройки (models, providers)
│   └── logger.py                 # Логирование
├── tests/
│   ├── test_code_executor.py
│   ├── test_tools.py
│   └── test_pydantic_extract.py
├── data/
│   └── sessions/                 # SQLite база чатов
├── mcpServers/                   # Сгенерированные API модули
│   └── finam/
│       ├── assets/
│       ├── market_data/
│       ├── account/
│       └── order/
├── pyproject.toml                # uv конфигурация
├── .env                          # Переменные окружения
└── README.md

🔐 Безопасность

⚠️ ВАЖНО: Текущая реализация использует exec() для выполнения кода — это НЕ безопасно для production.

Для продакшена рассмотрите:

Docker контейнеры — полная изоляция среды
Jupyter Kernel — через Jupyter Messaging Protocol
Pyodide — WebAssembly sandbox (но медленнее)

📚 Документация и ресурсы

Статьи автора

MCP (Model Context Protocol)

CodeAct

CodeAct Research Paper (Apple, 2024)
Cloudflare: Code Mode

Finam API

Frameworks

📄 Лицензия

Проект распространяется под лицензией MIT. См. файл LICENSE.

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
.streamlit		.streamlit
finam-mcp @ b06e0e4		finam-mcp @ b06e0e4
images		images
mcpServers		mcpServers
src		src
tests		tests
.dockerignore		.dockerignore
.env.example		.env.example
.gitignore		.gitignore
.gitmodules		.gitmodules
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
pyproject.toml		pyproject.toml
uv.lock		uv.lock

Folders and files

Latest commit

History

Repository files navigation