trading-mcp

MCP-сервис для торговых данных и технических индикаторов, построенный на базе uv + pydantic + akshare + TA-Lib.

Возможности проекта

• Предоставление запросов рыночных данных по акциям и расчет базовых технических индикаторов (K-линии, RSI, MA, MACD).

• Предоставление запросов фундаментальных данных для среднесрочных и долгосрочных инвестиций (основные показатели акций A-share, три основные финансовые отчетности акций США, основные показатели акций США).

• Единый уровень доступа к рыночным данным, поддерживающий акции A-share и акции США (например, AAPL.US).

• Инструментальный интерфейс MCP с поддержкой вывода в формате Markdown или JSON.

Архитектура проекта

• data/: Уровень доступа к рыночным данным. Интерфейс MarketDataClient + реализация AkshareMarketDataClient.

• services/: Уровень бизнес-логики. Преобразование сырых рыночных данных в стандартные структуры и запуск расчета индикаторов.

• indicators/: Инкапсуляция движка индикаторов. Единый вызов на основе TA-Lib.

• models/: Модели запросов и ответов инструментов (Pydantic).

• utils/: Форматирование вывода MCP (таблицы Markdown и т.д.).

• mcp_app.py / main.py: Точка входа в MCP-сервис и регистрация инструментов.

Структура каталогов

• config/: Определение конфигурации (Pydantic Settings).

• data/: Реализация клиента рыночных данных.

• indicators/: Движок расчета индикаторов.

• models/: Модели запросов/ответов.

• services/: Уровень бизнес-логики.

• tests/: Модульное тестирование.

• utils/: Форматирование вывода и вспомогательные инструменты.

• mcp_app.py: Регистрация инструментов MCP.

• main.py: Точка входа для запуска сервиса.

Установка и зависимости

1. Установка зависимостей:

uv sync --extra dev

2. Установка системной библиотеки TA-Lib:

• macOS: brew install ta-lib

• Debian/Ubuntu: sudo apt-get install libta-lib0 libta-lib0-dev

• Windows: используйте предварительно скомпилированный wheel для соответствующей версии Python

Описание конфигурации Конфигурация переопределяется через переменные окружения с префиксом TRADING_MCP_:

export TRADING_MCP_ENVIRONMENT=dev
export TRADING_MCP_DATA_DIR=./data
export TRADING_MCP_DEFAULT_SYMBOL=000001
export TRADING_MCP_HOST=0.0.0.0
export TRADING_MCP_PORT=8000
export TRADING_MCP_AKSHARE_PROXY_ENABLED=true
export TRADING_MCP_AKSHARE_PROXY_AUTH_IP=***
export TRADING_MCP_AKSHARE_PROXY_AUTH_TOKEN=*** TRADING_MCP_AKSHARE_PROXY_RETRY=30

Значения полей:

• TRADING_MCP_ENVIRONMENT: Идентификатор среды выполнения (например, dev / test / prod).

• TRADING_MCP_DATA_DIR: Локальный каталог данных.

• TRADING_MCP_DEFAULT_SYMBOL: Инструмент по умолчанию.

• TRADING_MCP_HOST: Адрес прослушивания MCP-сервиса.

• TRADING_MCP_PORT: Порт MCP-сервиса.

• TRADING_MCP_AKSHARE_PROXY_ENABLED: Включить ли akshare-proxy-patch.

• TRADING_MCP_AKSHARE_PROXY_AUTH_IP: IP шлюза авторизации akshare-proxy-patch; если не настроено, патч не будет установлен.

• TRADING_MCP_AKSHARE_PROXY_AUTH_TOKEN: Опциональный токен авторизации.

• TRADING_MCP_AKSHARE_PROXY_RETRY: Количество внутренних повторных попыток патча.

Примечание по прокси для защиты от парсинга (East Money):

• Проект содержит встроенный akshare-proxy-patch, который автоматически пытается установиться при импорте data/akshare_client.py.

• Активируется только при настроенном TRADING_MCP_AKSHARE_PROXY_AUTH_IP и TRADING_MCP_AKSHARE_PROXY_ENABLED=true.

• Патч перехватывает только запросы к доменам East Money и не влияет на другие сайты.

Использование в Python

from trading_mcp.config import Settings
from trading_mcp.data import AkshareMarketDataClient
from trading_mcp.indicators import IndicatorEngine

settings = Settings(environment="dev", data_dir="./data", default_symbol="000001")
client = AkshareMarketDataClient()
frame = client.fetch(settings.default_symbol, "2024-01-01", "2024-02-01")

engine = IndicatorEngine()
close_series = frame["close"] if "close" in frame.columns else frame.iloc[:, 0]
result = engine.compute("sma", close_series, timeperiod=5)
print(result.tail())

MCP-сервис Запуск MCP-сервиса (streamable HTTP):

python main.py

Запуск MCP Inspector (адаптирован для WSL, доступен с хост-машины):

./dev.sh

По умолчанию используются следующие настройки Inspector:

• MCP_INSPECTOR_HOST=0.0.0.0

• MCP_INSPECTOR_CLIENT_PORT=6274

• MCP_INSPECTOR_SERVER_PORT=6277

• MCP_INSPECTOR_AUTO_OPEN=false

В браузере на хост-машине Windows рекомендуется использовать:

http://localhost:6274

Если на локальной машине не включена переадресация localhost в WSL, можно выполнить hostname -I внутри WSL, чтобы узнать IP, а затем зайти с хост-машины по адресу http://<wsl-ip>:6274.

Если вы хотите доступ только из локальной среды Linux, можно переопределить на:

MCP_INSPECTOR_HOST=127.0.0.1 ./dev.sh

Внимание: прокси Inspector обладает способностью запускать локальные процессы. 0.0.0.0 следует использовать только в доверенных сетевых средах.

Доступные инструменты:

• trading_kline(symbol, limit=30, offset=0, period_type="1d", start_date=None, end_date=None, response_format="markdown")

• trading_macd(symbol, limit=30, fast_period=12, slow_period=26, signal_period=9, offset=0, period_type="1d", start_date=None, end_date=None, response_format="markdown")

• trading_rsi(symbol, limit=30, period=14, offset=0, period_type="1d", start_date=None, end_date=None, response_format="markdown")

• trading_ma(symbol, limit=30, period=20, ma_type="sma", offset=0, period_type="1d", start_date=None, end_date=None, response_format="markdown")

• trading_volume(symbol, limit=30, offset=0, period_type="1d", start_date=None, end_date=None, response_format="markdown")

• trading_fund_flow_individual_em(symbol, limit=30, offset=0, start_date=None, end_date=None, response_format="markdown")

• trading_fund_flow_individual_rank_em(indicator="5日", limit=30, offset=0, response_format="markdown")

• trading_fund_flow_sector_rank_em(indicator="今日", sector_type="行业资金流", sort_by="主力净流入", limit=30, offset=0, response_format="markdown")

• trading_fund_flow_sector_summary_em(symbol, indicator="今日", limit=30, offset=0, response_format="markdown")

• trading_fundamental_cn_indicators(symbol, indicator="按报告期", limit=30, offset=0, start_date=None, end_date=None, response_format="markdown")

• trading_fundamental_us_report(stock, symbol="资产负债表", indicator="年报", limit=30, offset=0, start_date=None, end_date=None, response_format="markdown")

• trading_fundamental_us_indicators(symbol, indicator="年报", limit=30, offset=0, start_date=None, end_date=None, response_format="markdown")

• trading_industry_summary_ths(limit=30, offset=0, response_format="markdown")

• trading_industry_index_ths(symbol, limit=30, offset=0, start_date=None, end_date=None, response_format="markdown")

• trading_industry_name_em(limit=30, offset=0, response_format="markdown")

• trading_board_change_em(limit=30, offset=0, response_format="markdown")

• trading_industry_spot_em(symbol, limit=30, offset=0, response_format="markdown")

• trading_industry_cons_em(symbol, limit=30, offset=0, response_format="markdown")

• trading_industry_hist_em(symbol, period="日k", adjust="none", limit=30, offset=0, start_date=None, end_date=None, response_format="markdown")

• trading_industry_hist_min_em(symbol, period="5", limit=30, offset=0, response_format="markdown")

• trading_info_global_em(limit=30, offset=0, response_format="markdown")

Описание параметров trading_fundamental_cn_indicators:

• indicator enum: 按报告期 (по отчетному периоду), 按单季度 (по кварталам)

• symbol совместимый ввод: 000001, 000001.SZ, 600519.SH (автодополнение или нормализация суффикса)

• Результаты фундаментальных данных возвращаются в формате исходных строк: columns + items

Описание параметров trading_fundamental_us_report:

• symbol (тип отчета) enum: 资产负债表 (баланс), 综合损益表 (отчет о прибылях и убытках), 现金流量表 (отчет о движении денежных средств)

• indicator (период отчета) enum: 年报 (годовой отчет), 单季报 (квартальный отчет), 累计季报 (накопительный квартальный отчет)

• stock совместимый ввод: TSLA, AAPL.US, 105.AAPL, BRK.B (внутренняя нормализация в тикер, распознаваемый AkShare)

Описание параметров trading_fundamental_us_indicators:

• indicator enum: 年报, 单季报, 累计季报

• symbol совместимый ввод: TSLA, AAPL.US, 105.AAPL, BRK.B

• Результаты фундаментальных данных возвращаются в формате исходных строк: columns + items

Описание полей trading_volume:

• Возвращаемые поля: timestamp, volume, amount, turnover_rate

• Стратегия единиц измерения: сохраняются исходные единицы источника данных, единицы возвращаются в полях ответа

  • A-share: volume_unit=lot, amount_unit=CNY

  • Акции США: volume_unit=share, amount_unit=USD

  • turnover_rate_unit=percent

• Если недельные/месячные данные агрегированы из дневных, turnover_rate может быть null

Описание инструментов потоков капитала:

• trading_fund_flow_individual_em: Потоки капитала по отдельным акциям (East Money), symbol поддерживает 000001, 600519.SH, 830799.BJ

• trading_fund_flow_individual_rank_em: Рейтинг потоков капитала по акциям (East Money)

  • indicator enum: 今日, 3日, 5日, 10日

• trading_fund_flow_sector_rank_em: Рейтинг потоков капитала по секторам (East Money)

  • indicator enum: 今日, 5日, 10日

  • sector_type enum: 行业资金流 (отраслевые), 概念资金流 (концептуальные), 地域资金流 (региональные)

  • sort_by enum: 涨跌幅 (изменение цены), 主力净流入 (чистый приток основных средств); по умолчанию сортировка по 主力净流入 по убыванию

• Если интерфейс рейтинга East Money недоступен:

  • Рейтинг акций переключается на рейтинг потоков капитала от Tonghuashun

  • Рейтинг отраслевых/концептуальных секторов переключается на соответствующий рейтинг Tonghuashun

  • После переключения возвращаемые столбцы могут отличаться от исходных столбцов East Money; 地域资金流 не переключается

• trading_fund_flow_sector_summary_em: Потоки капитала по компонентам указанного сектора

  • По умолчанию используется East Money, при сбое переключается на Tonghuashun

  • symbol — название сектора, например 电源设备 (силовое оборудование), 风电设备 (ветроэнергетическое оборудование)

  • indicator enum: 今日, 5日, 10日

  • После переключения возвращаемые столбцы могут отличаться от исходных столбцов East Money

• Результаты потоков капитала возвращаются в виде исходной таблицы: columns + items

Описание символов:

• Примеры A-share: 000001, 300308.SZ

• Примеры акций США: AAPL.US, AAPL, 105.AAPL, BRK.B

Описание инструментов отраслевых секторов:

• trading_industry_summary_ths: Сводная таблица отраслей Tonghuashun, возвращает исходные поля сводки секторов

• trading_industry_index_ths: Отраслевой индекс Tonghuashun, symbol — название сектора, поддерживает start_date / end_date

• trading_industry_name_em: Список названий отраслевых секторов East Money

• trading_board_change_em: Детали изменений секторов за день (East Money)

• trading_industry_spot_em: Рыночные данные отраслевых секторов в реальном времени (East Money), symbol — название сектора

• trading_industry_cons_em: Компоненты отраслевых секторов (East Money), symbol — название сектора

• trading_industry_hist_em: Исторические данные отраслевых секторов (East Money)

  • period enum: 日k (дневные), 周k (недельные), 月k (месячные)

  • adjust enum: none, qfq (с поправкой на дивиденды), hfq (с поправкой на дивиденды); none означает без поправки

• trading_industry_hist_min_em: Исторические внутридневные данные отраслевых секторов (East Money)

  • period enum: 1, 5, 15, 30, 60

• Результаты по отраслевым секторам возвращаются в виде исходной таблицы: columns + items

Описание инструментов новостей:

• trading_info_global_em: Глобальные финансовые новости (East Money)

• Результаты новостей возвращаются в виде исходной таблицы: columns + items

Структура ответа (structuredContent)

{
  "stock": "TSLA",
  "symbol": "资产负债表",
  "indicator": "年报",
  "columns": ["REPORT_DATE", "ITEM_NAME", "AMOUNT"],
  "items": [],
  "count": 0,
  "total": 0,
  "limit": 30,
  "offset": 0,
  "has_more": false,
  "next_offset": null,
  "start_date": null,
  "end_date": null
}

Процесс взаимодействия с данными MCP (архитектура и диаграмма последовательности)

Ниже с помощью Mermaid нарисованы основная архитектура взаимодействия с данными и диаграмма последовательности текущего MCP, чтобы помочь понять путь прохождения запроса в системе.

Схема архитектуры (Flowchart)

flowchart LR
  Client[Client / User] -->|HTTP/Stream 请求| MCP[MCP Server]
  MCP -->|调用工具接口| API[Tool Dispatcher / Handlers]
  API --> Market[MarketDataClient (Akshare / Providers)]
  Market -->|行情数据| Storage[Local Cache / Data Dir]
  API --> Indicator[IndicatorEngine (TA-Lib)]
  Indicator -->|指标结果| Formatter[Response Formatter (Markdown / JSON)]
  Formatter -->|返回| Client
  Market -.->|必要时| Proxy[akshare-proxy-patch]
  MCP -->|注册 & 管理| Inspector[MCP Inspector]

Пояснения:

• MCP Server: принимает внешние запросы (HTTP/stream), отвечает за разбор запроса и вызов внутренних инструментов.

• Tool Dispatcher: маршрутизирует запрос к конкретному инструменту (например, trading_kline, trading_macd).

• MarketDataClient: единый уровень доступа к рыночным данным, в настоящее время реализован в основном через Akshare, поддерживает патч прокси.

• IndicatorEngine: вызывает TA-Lib или встроенные алгоритмы для расчета технических индикаторов.

• Response Formatter: преобразует структурированные данные в формат ответа MCP (Markdown или JSON).

• Local Cache/Storage: используется для краткосрочного кэширования и хранения исторических данных для уменьшения количества вызовов API.

Диаграмма последовательности (Sequence Diagram)

sequenceDiagram
  participant U as Client/User
  participant M as MCP Server
  participant D as Tool Dispatcher
  participant MD as MarketDataClient
  participant I as IndicatorEngine
  participant F as Formatter

  U->>M: 发起 trading_macd 请求 (symbol, start, end, params)
  M->>D: 解析并转发请求
  D->>MD: 请求历史 K 线 (symbol, start, end)
  MD-->>D: 返回原始行情数据 (OHLCV)
  D->>I: 传入行情数据与参数, 调用指标计算
  I-->>D: 返回指标结果 (MACD lines, histogram)
  D->>F: 格式化为 Markdown / JSON 的 MCP 响应
  F-->>M: 返回格式化结果
  M-->>U: 通过 HTTP Stream 返回响应 (chunked / 完整)

  alt 缓存命中
    D->>Storage: 读取缓存
    Storage-->>D: 返回缓存数据
  end

  alt 第三方被阻断/需要代理
    MD->>Proxy: 走 akshare-proxy-patch
    Proxy-->>MD: 返回代理后的数据
  end

Вышеуказанные две диаграммы являются абстрактным представлением текущей системы; если вы хотите детализировать диаграммы до большего количества компонентов (например: аутентификация, ограничение скорости, очереди, асинхронные задачи, показатели мониторинга), сообщите мне, какие части нужно добавить, и я расширю и обновлю диаграммы Mermaid в README.

Если вы подтверждаете, что это обновление в порядке, я зафиксирую изменения в новой ветке и отправлю их, а затем создам Pull Request для проверки.