IntelliTrade：多代理交易大厅（MCP供电）
IntelliTrade是一个教学和实验项目，模拟了一个由自主AI交易者组成的小型交易大厅。每个交易者都是一个代理人，定期研究市场，做出决策，并根据磁盘上的账户分类账执行交易。代理通过模型上下文协议（MCP）工具和服务访问功能，包括：
- 投资组合状态和交易执行的账户服务
- 市场数据服务（基于多边形或本地回退）
- 推送交易摘要通知
- 研究服务（网络获取、搜索和每个交易者的记忆）
在幕后，代理通过stdio协调多个MCP服务器，记录跟踪和事件，并将持久状态存储在SQLite中。
--如果这对你有帮助，请⭐ 回购！
目录
- 概述
- 主要特点 - 为什么这个架构 - 项目结构 - 深度架构文档
- 入门指南
- 需求 - 环境变量 - 安装 - 快速入门矩阵 - 初始化交易者 - 经营交易大厅
- 内部机制
- 定价如何运作 - 数据存储 - 架构图 - 日志和可观察性 - 运行单个服务器（可选） - 开发说明和扩展点 - 可靠性和故障模式 - 安全和隐私 - 性能注意事项
- 故障排除
- 许可证
主要特点
- 具有不同策略的多个交易者角色
- 研究员工具作为网络研究的委托代理
- 用于账户、市场数据、通知和研究的MCP服务器
- SQLite支持的帐户、日志和市场缓存
- Polygon.io与实时或EOD回退集成
- 具有环境配置的定期调度
为什么这个架构
- 通过MCP进行隔离：提供可组合、过程隔离的MCP服务器功能，以实现清晰的接口和崩溃控制。
- 具有可插拔边缘的确定性核心：在数据提供者和研究工具交换时，核心交易循环仍然是可测试的。
- 回退弹性：如果Polygon不可用，当地市场MCP将保持EOD/随机定价的连续性。
- 可追溯性：所有代理活动都会被跟踪并写入审计日志，以进行事后分析。
项目结构
intellitrade/trading_floor.py：以节奏运行所有交易者的调度器intellitrade/traders.py：交易员代理编排和研究工具连接intellitrade/accounts.py：账户模型、交易、报告和日志记录intellitrade/accounts_server.py：暴露账户操作的MCP工具和资源intellitrade/accounts_client.py：客户端垫片调用账户MCP服务器/工具intellitrade/market.py：带缓存的Polygon API和回退定价实用程序intellitrade/market_server.py：本地MCP市场服务器（不使用Polygon工具时的备用）intellitrade/push_server.py：用于Pushover通知的MCP工具intellitrade/mcp_params.py：面向交易员和研究人员的MCP服务器启动参数intellitrade/templates.py：提示模板和任务消息intellitrade/tracers.py：将跨度/跟踪记录到SQLite的跟踪处理器intellitrade/database.py：用于帐户、日志和市场缓存的SQLite持久性intellitrade/reset.py：初始化四个交易者角色及其策略intellitrade/memory/*.db：研究人员MCP服务器的每个交易者内存数据库intellitrade/accounts.db：用于帐户、日志、市场缓存的主SQLite数据库
深度架构文档
如需更深入地了解其他图表和内部结构，请参阅：
docs/ARCHITECTURE.md
需求
- Python 3.12+
uv用于运行Python应用程序和管理deps- \[
node和npx\]对于某些MCP服务器（Brave搜索和内存服务器）
Python依赖关系在 pyproject.toml 并被固定住 uv.lock.
环境变量
- 核心：
- POLYGON_API_KEY：Polygon.io API密钥（可选；启用Polygon-based定价） - POLYGON_PLAN：其中之一 paid 或 realtime 解锁更丰富的多边形工具 - PUSHOVER_USER, PUSHOVER_TOKEN：推送通知的凭据（可选） - RUN_EVERY_N_MINUTES：调度程序节奏（默认值： 60) - RUN_EVEN_WHEN_MARKET_IS_CLOSED: true 无论市场时间如何，都要跑步 - USE_MANY_MODELS: true 为每个交易者分配不同的LLM后端
- LLM/OpenRouter样式密钥（可选；使用您打算测试的密钥）：
- OPENROUTER_API_KEY, DEEPSEEK_API_KEY, GROK_API_KEY, GOOGLE_API_KEY
- 研究/搜索：
- BRAVE_API_KEY：适用于Brave Search MCP服务器（可选；推荐）
创建一个 .env 在repo根目录中配置这些：
POLYGON_API_KEY=...
POLYGON_PLAN=paid
PUSHOVER_USER=...
PUSHOVER_TOKEN=...
RUN_EVERY_N_MINUTES=30
RUN_EVEN_WHEN_MARKET_IS_CLOSED=false
USE_MANY_MODELS=false
BRAVE_API_KEY=...
OPENROUTER_API_KEY=...安装
# Ensure uv is installed, see uv docs if needed
uv sync这将解决并准备基于以下内容的环境 pyproject.toml 和 uv.lock.
快速入门矩阵
- 实时多边形：设置
POLYGON_API_KEY和POLYGON_PLAN=realtime→ 使用多边形MCP工具 - 付费多边形（延迟）：设置
POLYGON_API_KEY和POLYGON_PLAN=paid→ 使用延迟快照工具 - 无多边形：省略
POLYGON_API_KEY→ 使用本地market_server.py带EOD/随机回退的MCP
初始化交易者
uv run intellitrade/reset.py这会创建或重置四个具有策略的交易者：
- 沃伦（价值，长期）
- 乔治（宏观，逆向）
- Ray（系统性、风险平价）
- Cathie（颠覆性创新，加密货币ETF重点）
经营交易大厅
uv run intellitrade/trading_floor.py发生了什么：
- 调度器循环每个
RUN_EVERY_N_MINUTES - 当市场开放时（或如果设置了覆盖），所有交易者同时运行
- 每位交易员：
- 通过账户MCP服务器读取他们的账户和策略 - 将研究委托给连接到多个研究MCP服务器的研究员代理 - 通过Polygon MCP工具或本地市场服务器查询市场数据 - 使用账户MCP服务器执行交易 - 发送简短的推送通知（如果已配置） - 将跟踪和操作记录到SQLite
定价如何运作
- 如果
POLYGON_API_KEY已设置：
- 随着 POLYGON_PLAN=realtime：使用实时快照工具 - 随着 POLYGON_PLAN=paid：使用延迟快照工具
- 否则：
- 本地MCP服务器(intellitrade/market_server.py)提供EOD或随机回退（带磁盘缓存）
数据存储
intellitrade/accounts.db（SQLite）：
- accounts：按交易员姓名列出的JSON账户状态 - logs：按交易员姓名列出的跟踪和事件日志 - market：按日期键入的EOD市场缓存
intellitrade/memory/.db：每个交易者的研究工具内存
架构图
组件视图：
flowchart LR
subgraph Agents
T1[Trader: Warren]
T2[Trader: George]
T3[Trader: Ray]
T4[Trader: Cathie]
R[Researcher Agent]
end
subgraph MCP Servers
A[Accounts MCP\n(accounts_server.py)]
M{{Market MCP\n(Polygon or market_server.py)}}
P[Push MCP\n(push_server.py)]
F[Fetch MCP\n(mcp-server-fetch)]
B[Brave Search MCP]
MM[Memory MCP\n(mcp-memory-libsql)]
end
subgraph Persistence
DB[(SQLite\naccounts.db)]
MEM[(Per-Trader Memory\nmemory/*.db)]
end
T1 -- read/write --> A
T2 -- read/write --> A
T3 -- read/write --> A
T4 -- read/write --> A
T1 -- price/info --> M
T2 -- price/info --> M
T3 -- price/info --> M
T4 -- price/info --> M
T1 -- notify --> P
T2 -- notify --> P
T3 -- notify --> P
T4 -- notify --> P
T1 R
T2 R
T3 R
T4 R
R -- fetch --> F
R -- search --> B
R -- recall/store --> MM
A DB
MM MEM交易回合的顺序：
sequenceDiagram
participant Scheduler as trading_floor.py
participant Trader as Trader Agent
participant Researcher as Researcher Agent
participant Accounts as Accounts MCP
participant Market as Market MCP
participant Push as Push MCP
participant DB as SQLite (accounts.db)
Scheduler->>Trader: run()
Trader->>Accounts: read_account(name)
Accounts->>DB: SELECT accounts, logs
Accounts-->>Trader: account JSON + metadata
Trader->>Researcher: research_tool(request)
Researcher->>Market: query price/info (via MCP or Polygon)
Researcher-->>Trader: findings summary
Trader->>Accounts: buy_shares/sell_shares(name,symbol,qty,rationale)
Accounts->>Market: get_share_price(symbol)
Market-->>Accounts: price
Accounts->>DB: UPDATE accounts; INSERT logs
Accounts-->>Trader: trade confirmation + report JSON
Trader->>Push: push("summary of trades and outlook")
Push-->>Trader: ok
Trader-->>Scheduler: completed日志和可观察性
- 痕迹和跨度通过以下方式持久化
tracers.LogTracer到logs桌子 - 你可以探索
intellitrade/accounts.db使用任何SQLite工具进行检查：
- 每位交易者最近的行为(logs) - 账户状态(accounts) - 缓存EOD价格(market)
操作提示：
- 跟踪ID是通过以下方式从交易者姓名中导出的
tracers.make_trace_id为了便于关联。 - 系统记录跟踪开始/结束和跨度级别的事件，并为事后分析提供可选的错误字符串。
运行单个服务器（可选）
通常，交易者会根据需要启动MCP服务器。您也可以手动运行它们：
# Accounts MCP server
uv run intellitrade/accounts_server.py
# Local Market MCP server (fallback when not using Polygon MCP tools)
uv run intellitrade/market_server.py
# Push MCP server
uv run intellitrade/push_server.py开发说明和扩展点
- MCP服务器参数集中在
intellitrade/mcp_params.py - 定价逻辑和回退路径在
intellitrade/market.py - 账户操作（买入/卖出/报告/策略）
intellitrade/accounts.py - 交易员在每个周期的“交易”和“再平衡”运行之间切换
- 研究人员代理作为单一工具暴露在交易者面前
- 添加新的数据提供程序：扩展
mcp_params.py使用新的MCP条目并将其工具集成到traders.py或研究人员代理人。 - 添加新交易者：更新
intellitrade/trading_floor.py种子战略intellitrade/reset.py. - 添加新通知：实现类似于以下内容的MCP工具
push_server.py.
可靠性和故障模式
- MCP过程隔离包含单个工具内的故障；即使某些工具失败，交易者的挤兑也可以继续进行。
- 市场定价存在分层回落：实时→ 延迟→ EOD缓存→ 随机。
- 在SQLite级别，帐户操作是事务性的；每个交易者的操作最大限度地减少了写争用。
- 研究服务器可能会设置速率限制；提示指示回退到备用获取工具。
安全和隐私
- 从读取API密钥
.env并且不保存在数据库中。 - SQLite存储帐户状态、日志和市场缓存。研究记忆数据库是每个交易者和本地的。
- 这里的MCP传输是本地stdio；如果引入了远程执行，请使用安全通道和身份验证。
性能注意事项
- 交易员在每个周期同时运行；重型IO被隔离在外部MCP进程中。
- 市场EOD结果按日期缓存，以减少API调用（LRU+SQLite缓存）。
- 调谐
RUN_EVERY_N_MINUTES迭代速度与负载的关系；尽可能整合MCP启动，以实现长期会话。
故障排除
- 缺少多边形密钥：系统退回EOD/随机定价；集
POLYGON_API_KEY提高保真度 - 缺少Brave密钥：研究仍然可以通过fetch进行，但搜索质量会随着
BRAVE_API_KEY - 无推送：确保
PUSHOVER_USER和PUSHOVER_TOKEN设置或禁用流中的通知 - MCP启动问题：确保
uv,node，以及npx已安装并位于PATH中
许可证
此存储库用于教育和实验用途。如果没有另行规定，请咨询项目所有者以了解许可条款。