alpaca-trading-paper-trading-mcp

Alpaca 模拟交易 — MCP 服务版本

当你想让 AI Agent 使用 Alpaca Trading API MCP 服务预览、提交、检查和管理模拟交易订单时，请使用此技能。

此技能面向你——使用自己的 Alpaca 模拟交易账户的 Trading API 用户。你的 Agent 会直接调用 MCP 工具，无需安装 CLI 或发送原始 HTTP 请求。MCP 服务负责处理身份验证和 API 通信。

这是 MCP 服务专用版本。另有通用（与实现无关）版本和 CLI 版本可作为配套技能使用。

---

0 — AI Agent 应如何使用此技能

1. 从信号来源着手。 无论信号来自回测结果、手动交易想法、定时触发器还是对话请求，都要明确是什么在驱动这笔交易。
2. 重述策略逻辑并向你确认。 你的 Agent 必须用自己的话重述交易想法，并在继续操作前等待你的确认。
3. 收集并确认所有配置。 包括时间、资产类别、交易代码、方向、数量或名义金额、订单类型、有效期限、限价／止损价、盘后交易标记、风险控制（持仓限额、最大订单规模、亏损阈值）以及保证金意图。
4. 查找可用的 MCP 工具。 你的 Agent 必须调用 GetDynamicTools，查找 Alpaca MCP 命名空间，并在调用任何工具前检查可用工具的架构。工具名称和参数因 MCP 服务实现而异——切勿想当然。
5. 验证模拟环境。 从主机的 MCP 配置文件中读取 env.ALPACA_PAPER_TRADE——没有工具能提供此信息——并要求其值为空、true、1 或 yes。随后确认账户处于活动状态且未受限制。如果无法证明处于模拟模式，立即停止并告知你。
6. 显示完整的订单预览表。 提交前，你必须能看到将发送给下单工具的每个参数。
7. 询问你是否希望在每笔订单前明确确认（默认：开启）。在本次会话剩余时间内遵循你的偏好。
8. 通过对应资产类别的下单工具提交。 下单工具按股票、加密货币和期权分别提供——先按资产类别选择工具，再准确传入已确认且与预览一致的参数。
9. 使用订单查询和订单列表工具进行监控。 报告成交、拒绝、部分成交情况及其对投资组合的影响。
10. 绝不进行实盘交易。 每次提交前都要验证模拟环境。

---

1 — 前提条件

必需

• 已在 Agent 主机（Cursor 等）中安装并配置 Alpaca Trading API MCP Server
• 在 MCP 服务配置中将模拟交易 API 密钥和密钥 Secret配置为环境变量——切勿粘贴到聊天中或作为工具参数传入
• 可通过 GetDynamicTools 查找到 MCP 服务命名空间
• Alpaca 模拟交易账户处于活动状态

有条件要求

• 期权交易：必须在你的 Alpaca 模拟账户中启用
• 加密货币交易：必须在你的 Alpaca 模拟账户中启用

MCP 服务配置（Cursor）

该服务是 Alpaca 的官方 MCP 服务，由 alpacahq/alpaca-mcp-server 维护。该仓库的 README 是包名、命令和环境变量的权威来源。以下配置对应 v2。

将其添加到 ~/.cursor/mcp.json：

{
  "mcpServers": {
    "alpaca-paper-trading": {
      "command": "uvx",
      "args": ["alpaca-mcp-server"],
      "env": {
        "ALPACA_API_KEY": "your-paper-key",
        "ALPACA_SECRET_KEY": "your-paper-secret",
        "ALPACA_PAPER_TRADE": "true"
      }
    }
  }
}

变量	必填	默认值	用途
ALPACA_API_KEY	是	—	模拟交易 API 密钥
ALPACA_SECRET_KEY	是	—	模拟交易密钥
ALPACA_PAPER_TRADE	否	true	模拟交易/实盘开关；false 表示选择实盘。此技能要求设为 true。
ALPACA_TOOLSETS	否	全部	要公开的逗号分隔工具集。留空表示拥有所有功能。只有在需要限制 Agent 可访问的内容时才设置（例如 account,trading,assets）。

模拟交易还是实盘交易仅由 ALPACA_PAPER_TRADE 决定。服务会根据该标志推导 API 主机，因此无需设置或验证基础 URL 变量。

验证 MCP 服务是否可用

你的 Agent 应运行：

GetDynamicTools with pattern "alpaca"

如果找不到命名空间、其状态显示为 "error" 或 "loading"，或者 namespaceStatus: "needsAuth"：

1. 如果为 "needsAuth"，请通过该命名空间的 mcp_auth 进行身份验证，然后重试。
2. 如果为 "error" 或找不到命名空间，请让你检查 Cursor 设置中的 MCP 服务配置。
3. 不要回退到直接 HTTP 调用或 CLI 命令。这是 MCP 版本。

---

2 — 收集输入

输入表

参数	必填	默认值	说明
symbol	是	—	股票代码（例如：AAPL、BTC/USD、AAPL251219C00250000）
side	是	—	buy 或 sell
qty	qty/notional 二选一	—	股数/单位数量。可为整数或小数。与 notional 互斥
notional	qty/notional 二选一	—	美元金额。股票：仅支持 day TIF 的市价单。加密货币：仅支持市价单。place_option_order 不支持
type	否	market	股票：market、limit、stop、stop_limit、trailing_stop。加密货币：market、limit、stop_limit。期权：market、limit。参数名是 type，不是 order_type
time_in_force	否	股票为 day，加密货币为 gtc，期权为 day	股票：day、gtc、opg、cls、ioc、fok。加密货币：仅支持 gtc 或 ioc——不接受 day 和 fok。期权：仅支持 day
limit_price	limit/stop_limit 时必填	—	限价
stop_price	stop/stop_limit 时必填	—	止损触发价
trail_percent	trailing_stop 时必填	—	移动止损百分比。仅适用于 place_stock_order
trail_price	trailing_stop 时必填	—	移动止损美元偏移量。仅适用于 place_stock_order
extended_hours	否	false	允许在延长交易时段成交。仅适用于 place_stock_order；类型须为 limit，TIF 须为 day 或 gtc
client_order_id	否	若省略则由 Alpaca 生成	幂等键——你的 Agent 为每笔订单生成一个
order_class	否	null	simple、bracket、oco、oto。仅适用于 place_stock_order。提供下方任一括号单腿参数时，会自动设为 bracket
take_profit_limit_price	括号单时必填	—	止盈腿的限价。仅适用于 place_stock_order
stop_loss_stop_price	括号单时必填	—	止损腿的止损价。仅适用于 place_stock_order
stop_loss_limit_price	否	—	止损腿的限价。需要提供 stop_loss_stop_price
position_intent	否	—	buy_to_open、buy_to_close、sell_to_open、sell_to_close（期权）

括号单的各腿使用扁平标量参数，而非嵌套对象。POST /v2/orders 接受嵌套的 take_profit: { limit_price } 和 stop_loss: { stop_price, limit_price }，但 place_* 工具会将它们扁平化，且其架构设置了 additionalProperties: false——因此传入嵌套的 REST 结构会被直接拒绝，而不是静默忽略字段。这是一个普遍的注意事项：这些工具会有意重塑 REST 请求体，因此切勿根据 REST 架构构建参数。

收集的其他背景信息

输入	必填	默认值	说明
asset_class	推断得出	us_equity	us_equity、crypto、us_option
strategy_description	建议提供	—	对交易理由的自然语言描述
risk_controls	建议提供	—	最大持仓规模、最大亏损阈值、投资组合集中度限制
mcp_namespace	发现得出	—	Alpaca 工具可用的 MCP 命名空间（通过 GetDynamicTools 获取）

策略确认清单

继续进行订单预览前，你的 Agent 必须确认：

• 用通俗语言重述策略意图
• 确认股票代码、买卖方向及数量/名义金额
• 确认订单类型和所有价格水平
• 确认有效期限
• 确认延长交易时段意图（股票）
• 确认风险控制措施（或明确放弃）
• 确认资产类别的特定要求（期权交易权限、加密货币资格）
• 验证模拟环境

---

3 — 真相来源参考资料

来源	URL	用途
Alpaca MCP Server	https://github.com/alpacahq/alpaca-mcp-server	服务设置、环境变量、工具集、当前工具列表
Alpaca Trading API 文档	https://docs.alpaca.markets/us/docs/trading-api	订单参数、账户字段、资产详情
Create Order 参考	https://docs.alpaca.markets/us/reference/postorder	仅用于底层 REST 语义——不是工具参数结构。place_* 工具会将此架构扁平化并加以约束，因此始终根据发现的工具架构构建参数
订单类型指南	https://docs.alpaca.markets/us/docs/orders-at-alpaca	订单类型行为、TIF 规则、延长交易时段
期权交易	https://docs.alpaca.markets/us/docs/options-trading	期权订单要求、行权／指派
加密货币交易	https://docs.alpaca.markets/us/docs/crypto-trading	加密货币交易对、全天候交易、零碎单位
账户 API	https://docs.alpaca.markets/us/reference/getaccount-1	账户状态字段、购买力、PDT
Alpaca 披露信息	https://alpaca.markets/disclosures	披露说明

发现规则

调用任何工具之前，你的 Agent 必须调用 GetDynamicTools，以发现实际的 MCP 命名空间、工具名称和参数架构。本技能提及的名称来自 v2 官方服务；请确认名称，切勿假定参数格式。

---

4 — 工作流

阶段 1：确认策略

步骤 1 — 确定信号来源。

确定交易想法的来源：

• 回测结果（引用运行文件夹和信号）
• 你的手动想法（“我想买入 100 股 AAPL”）
• 定时或条件触发（“AAPL 跌破 $180 时买入”）
• 投资组合再平衡（“平掉我的 TSLA 持仓，转投 NVDA”）

步骤 2 — 重述策略。

你的 Agent 用自己的话重述交易：

“你想在模拟账户中以市价单买入 10 股 AAPL，当日有效。这是一笔手动方向性交易——未附带止损或止盈。这样对吗？”

步骤 3 — 等待你的确认。

在你确认之前，不要继续。如果你更正了任何细节，你的 Agent 应再次确认更新后的内容。

阶段 2：确认配置

步骤 4 — 从上方的输入表中收集所有订单参数。

步骤 5 — 对于限价单、止损单或括号单，确认所有价格水平。

步骤 6 — 确认有效期和延长交易时段设置。

步骤 7 — 确认风险控制：

• 此证券的最大持仓规模
• 单笔订单最大名义价值
• 投资组合集中度限制
• 止损或止盈水平（如为括号单）

步骤 8 — 对于期权：确认合约代码、持仓意图（buy_to_open 等），以及期权交易已启用。

步骤 9 — 对于加密货币：确认交易对（例如 BTC/USD）、数量精度，以及是否全天候可交易。

阶段 3：MCP 发现与模拟账户验证

步骤 10 — 发现 Alpaca MCP 命名空间。

Call GetDynamicTools with pattern "alpaca" to find the namespace.
Then call GetDynamicTools with the found namespace to list all available tools.

你的 Agent 检查可用工具及其参数架构。每次会话都必须执行此步骤——工具名称和架构可能会随 MCP 服务版本而变化。

步骤 11 — 通过 MCP 获取账户状态。

调用账户信息工具——截至 v2 的名称为 get_account_info；请根据发现结果确认名称。

根据响应，验证：

• status = ACTIVE
• trading_blocked = false
• account_blocked = false

模拟交易模式由服务的 ALPACA_PAPER_TRADE 设置决定，而非这些字段。

步骤 12 — 停止关卡：通过 MCP 客户端配置证明处于模拟交易模式；如果无法证明，则停止。

MCP 服务不会向你的 Agent 暴露 ALPACA_PAPER_TRADE。没有任何工具、资源或服务指令字段会报告该值，因此 Agent 无法向服务询问当前所处模式。只有在客户端自己的 MCP 配置文件中才能读取该值。 该文件还在同一个 env 块中保存了 ALPACA_API_KEY 和 ALPACA_SECRET_KEY，因此你的 Agent 不得读取整个文件——不能使用 cat、文件读取工具，也不能打印服务器条目。读取整个文件会将凭据载入模型上下文，违反第 8 节中的数据处理保证。门禁只需要一个值，因此只提取这一个值：

# 1. List server names (names are not secrets)
jq -r '.mcpServers | keys[]' ~/.cursor/mcp.json

# 2. Confirm the chosen entry exists, then read only the flag
jq -r '.mcpServers | has("<server-name>")' ~/.cursor/mcp.json
jq -r '.mcpServers["<server-name>"].env.ALPACA_PAPER_TRADE // "unset"' ~/.cursor/mcp.json

在没有 jq 的主机上，读取单个值的等效方式：

python3 -c 'import json,sys;d=json.load(open(sys.argv[1]));e=d["mcpServers"][sys.argv[2]].get("env") or {};print(e.get("ALPACA_PAPER_TRADE","unset"))' ~/.cursor/mcp.json '<server-name>'

如果主机不是 Cursor，请替换为该主机自己的配置路径。然后，你的 Agent：

1. 找出为其发现 Alpaca 工具的命名空间提供支持的服务器条目，并确认该条目存在——即上文的第 2 步。
2. 要求该标志未设置，或设置为 true、1 或 yes（不区分大小写）。服务器会将值转换为小写，并检查它是否恰好属于这个集合，因此，任何其他值都会选择实盘模式——包括 paper、末尾带空格的 TRUE ，以及 yes!。

要区分读取结果为空的两种情况，因为它们并不等同。已确认的条目中，该标志未设置时通过——变量缺失时，服务器默认使用模拟交易模式。找不到条目或无法解析配置时，读取结果是无法判定，而不是通过；这类情况打印出的值与标志确实缺失时无法区分。绝不能把后一种情况当作前一种情况。

如果无法读取或解析配置、无法识别服务器条目，或值不属于该集合，门禁将默认拒绝。你的 Agent 会停止并告诉你：

"⚠️ 我无法确认此 MCP 服务处于模拟交易模式。此技能仅支持模拟交易。请检查服务器的 env 块中 ALPACA_PAPER_TRADE 是否为 true，并确认配置的密钥是模拟交易密钥，然后重启客户端。"

你的 Agent 绝不能把账户响应当作证明。实盘和模拟交易账户返回的结构相同，因此账户载荷本身永远无法证明环境——将未经证实的情况视为实盘。有两个较弱的信号可以佐证通过的配置检查，但绝不能替代它：模拟交易账户的 account_number 通常以 PA 开头，status 也可能是 PAPER_ONLY。两者都不是文档保证。

无论如何，只要无法证实处于模拟交易模式，就不要继续。

第 13 步——检查账户响应中的以下内容：

• buying_power——是否足以支付计划中的订单
• options_trading_level——如果交易期权。该值为有效等级（options_approved_level 与配置的 max_options_trading_level 两者中的较低值），因此应以它作为门槛，而不是 options_approved_level
• options_buying_power——如果交易期权
• crypto_status——如果交易加密货币
• multiplier——保证金分类，也是账户对象中唯一的 PDT 信号：4 表示 PDT 账户

账户对象没有 pattern_day_trader、daytrade_count 或 daytrading_buying_power 字段。你的 Agent 不得读取这些字段。

第 14 步——显示账户摘要：

┌─────────────────────────────────────────┐
│         Paper Account Summary           │
├─────────────────────┬───────────────────┤
│ Account ID          │ xxxxxxxx          │
│ Status              │ ACTIVE            │
│ Environment         │ PAPER             │
│ Equity              │ $100,000.00       │
│ Buying Power        │ $200,000.00       │
│ Cash                │ $100,000.00       │
│ Options Approved    │ Level 2           │
│ Crypto Status       │ ACTIVE            │
│ PDT                 │ No                │
└─────────────────────┴───────────────────┘

第 4 阶段：订单预览

第 15 步——构建订单参数对象。此时不要调用提交工具。

构建将传给第 19 步中所选订单下单工具的确切参数集：

{
  "symbol": "AAPL",
  "side": "buy",
  "qty": "10",
  "type": "limit",
  "limit_price": "185.50",
  "time_in_force": "day",
  "client_order_id": "pt-20260726-001-aapl-buy"
}

第 16 步——显示订单预览：

┌─────────────────────────────────────────┐
│           ORDER PREVIEW                 │
├─────────────────────┬───────────────────┤
│ Symbol              │ AAPL              │
│ Side                │ BUY               │
│ Quantity            │ 10 shares         │
│ Order Type          │ LIMIT             │
│ Limit Price         │ $185.50           │
│ Time in Force       │ DAY               │
│ Extended Hours      │ No                │
│ Order Class         │ Simple            │
│ Est. Notional       │ $1,855.00         │
│ Client Order ID     │ pt-20260726-...   │
│ Environment         │ PAPER (verified)  │
├─────────────────────┴───────────────────┤
│ ⚠ Paper trading only. Not financial    │
│   advice. Past performance ≠ future.   │
└─────────────────────────────────────────┘

第 17 步——如果确认功能已开启（默认）：等待你明确回复“yes”或“go ahead”后再提交。

第 18 步——如果你此前已关闭确认功能：显示预览，稍作停顿以便你阅读，然后继续。

阶段 5：通过 MCP 提交订单

步骤 19 — 根据资产类别选择下单工具，然后调用该工具。

没有统一的创建订单工具。下单按资产类别拆分，因此应根据步骤 7 中确认的资产类别选择工具：

资产类别	工具（截至 v2）	支持的订单类型
美国股票 / ETF	place_stock_order	市价单、限价单、止损单、止损限价单、追踪止损单、括号单
加密货币	place_crypto_order	市价单、限价单、止损限价单
美国期权	place_option_order	单腿和多腿

每个工具都有自己的参数架构——股票支持的订单类型并非都适用于加密货币，因此请查阅所选特定工具的参数架构，而不要重复使用其他工具的参数。调用前请根据工具发现结果确认名称和参数；以上名称是 v2 的当前名称，不保证在不同版本中保持不变。

Call place_stock_order with:
  symbol: "AAPL"
  side: "buy"
  qty: "10"
  type: "limit"
  limit_price: "185.50"
  time_in_force: "day"
  client_order_id: "pt-20260726-001-aapl-buy"

步骤 20 — 解析响应。

从 MCP 响应中提取：

• id — Alpaca 订单 ID
• client_order_id — 你的幂等键
• status — 订单初始状态（new、accepted、pending_new）
• created_at — 提交时间戳
• filled_qty、filled_avg_price — 如果订单立即成交（市价单）

步骤 21 — 发生失败时：

如果 MCP 工具调用返回错误：

错误类型	操作
购买力不足	显示当前购买力，建议减少数量或使用限价单
符号无效	使用资产查询工具（截至 v2 为 get_asset）验证符号，并建议更正
参数无效	显示未通过验证的参数，并参考正确的参数架构
市场已关闭（day TIF）	使用时钟工具显示市场交易时间，建议使用 gtc 或等待市场开盘
未启用期权交易	告知你在 Alpaca 控制面板中启用期权交易
账户受限	显示限制原因，并建议联系 Alpaca 支持
MCP 工具错误	显示原始错误，并建议检查 MCP 服务日志

在 order_log.csv 中记录失败尝试，状态设为 FAILED，并记录错误消息。

阶段 6：通过 MCP 进行提交后监控

步骤 22 — 检查订单状态。

调用单笔订单查询工具——截至 v2 为 get_order_by_id——并传入步骤 20 中的订单 ID。如果提交结果不明确且没有订单 ID，则改用幂等键查询订单，调用 get_order_by_client_id。

报告当前状态和任何成交信息。

步骤 23 — 列出所有未结订单（如有请求或作为有用的上下文）。

调用订单列表工具——截至 v2 为 get_orders——并筛选未结订单。

显示所有未结订单的摘要表格。

步骤 24 — 返回订单摘要：

┌─────────────────────────────────────────┐
│           ORDER SUBMITTED               │
├─────────────────────┬───────────────────┤
│ Order ID            │ abc-123-def       │
│ Symbol              │ AAPL              │
│ Side                │ BUY               │
│ Qty                 │ 10                │
│ Type                │ LIMIT @ $185.50   │
│ Status              │ NEW               │
│ Submitted           │ 2026-07-26 15:30  │
│ Environment         │ PAPER (verified)  │
├─────────────────────┴───────────────────┤
│ Next: Check status, modify, or cancel.  │
└─────────────────────────────────────────┘

步骤 25 — 报告订单生命周期。

随着订单状态变化，你的 Agent 会报告状态转换：

状态	向你报告的内容
new / accepted	订单已生效，等待成交
partially_filled	显示已成交数量、剩余数量和平均成交价格
filled	显示总成交数量、平均成交价格和预估成本
canceled	确认已取消，并显示任何已成交部分
expired	说明订单已过期（TIF 已结束）；如合适，建议重新提交
rejected	显示拒绝原因，并建议补救措施
replaced	显示旧订单 → 新订单的详细信息

对于已成交或部分成交的订单，计算对投资组合的影响：

• 新持仓规模（或现有持仓的变化）
• 预估成本基础
• 剩余购买力
• 该持仓在投资组合中的权重

阶段 7：通过 MCP 查看投资组合影响

步骤 26 — 获取所有持仓。

调用所有持仓工具 — get_all_positions（v2）。

显示持仓汇总表。

步骤 27 — 获取指定持仓（检查单个代码时）。

针对相关代码调用单个持仓工具 — get_open_position（v2）。

显示持仓详情：数量、平均入场价、当前价格、未实现盈亏、市场价值。

步骤 28 — 获取更新后的账户信息。

再次调用账户信息工具 — get_account_info（v2）。

显示交易后的更新净值、购买力和现金。

步骤 29 — 投资组合风险摘要：

┌─────────────────────────────────────────────┐
│         Portfolio Risk Summary              │
├──────────────────┬──────────────────────────┤
│ Total Equity     │ $99,850.00              │
│ Cash             │ $98,000.00              │
│ Market Value     │ $1,855.00               │
│ Buying Power     │ $196,000.00             │
│ Positions        │ 1                       │
│ Largest Position │ AAPL (100% of invested) │
│ Unrealized P&L   │ +$5.00 (+0.27%)         │
│ Day P&L          │ +$5.00                  │
└──────────────────┴──────────────────────────┘

阶段 8：通过 MCP 管理订单

步骤 30 — 取消指定订单。

使用订单 ID 调用取消单个订单工具 — cancel_order_by_id（v2）。

确认取消结果。注意：已成交的订单无法取消。

步骤 31 — 取消所有未完成订单。

调用批量取消工具 — cancel_all_orders（v2）。该工具会一次性处理账户中的每笔未完成订单，因此即使确认模式为 OFF，也要先显示将受影响的订单列表并获得确认，再调用该工具。

确认已取消的订单数量。列出无法取消的订单（已成交／正在成交）。

步骤 32 — 替换（修改）现有订单。

使用订单 ID 和仅包含需要修改的字段调用替换工具 — replace_order_by_id（v2）。

显示修改前 → 修改后的对比表。只有未成交或部分成交的订单可以替换。

步骤 33 — 平掉单个持仓。

调用平掉单个持仓工具 — close_position（v2）。该工具需要 symbol_or_asset_id，并可选填 qty 或 percentage，两者不能同时填写。两者都省略时，将平掉整个持仓。

这不是取消操作 — 它会为该持仓提交市价卖单，因此会动用真实（模拟）资金，并受市场交易时段限制。如果市场休市，订单会排队等待下次开盘时执行，这意味着你批准时并不知道成交价格。市场休市时，你的 Agent 会明确说明这一点，而不会暗示持仓已经清零。

你的 Agent 会显示即将平掉的持仓 — 代码、数量、市场价值和未实现盈亏 — 并要求明确确认。确认模式适用于下单，而这属于下单，因此 OFF 设置不会跳过清算确认。调用后，它会报告生成的订单 ID，并像处理其他订单一样持续跟踪，直到订单达到终态。

步骤 34 — 平掉所有持仓。

调用批量平仓工具 — close_all_positions（v2）。其唯一参数 cancel_orders 设为 true 时，会在清算前取消所有未完成订单。

这是此技能中破坏性最大的操作：它会清算整个投资组合，包括本次会话从未开立的持仓；如果设置 cancel_orders: true，还会撤销所有挂单。你的 Agent 会先显示所有将受影响的内容：

• 来自持仓列表工具的每笔未平仓持仓，包括代码、数量、市场价值和未实现盈亏
• 将被清算的总市场价值
• 如果要设置该标志，则列出 cancel_orders: true 将取消的所有未完成订单

接着，它会说明数量，并始终要求明确回复“yes”，不受 confirmation_mode 影响。只有获得确认后，才会调用工具。随后，它会报告平仓的持仓数量，并指出任何失败的持仓，因为部分失败会导致投资组合处于部分清算状态，你需要了解这一情况。

步骤 35 — 行权期权。

行权不可撤销，且结算结果会转为标的资产，因此 exercise_options_position 和 do_not_exercise_options_position（v2）都与步骤 34 一样，必须获得明确确认。调用任一工具前，你的 Agent 都会显示合约、由此产生的标的资产义务以及现金影响，并且绝不会主动发出行权指令。

阶段 9：部署指南（按需提供）

如果你询问如何在交互式会话之外自动执行这些交易：

基于 MCP 的自动化

• MCP 服务采用基于会话的方式，通常在 Cursor 等 Agent 宿主中运行
• 如需定期进行基于 MCP 的交易，可了解 Cursor 自动化或计划触发的 Agent
• 每次会话都必须运行并验证 MCP 服务的身份

独立自动化

• 如需用于生产环境的自动化，请直接使用 Alpaca SDK：
  • Python：alpaca-py（pip install alpaca-py）
  • TypeScript/JavaScript：@alpacahq/alpaca-trade-api 或 @alpacahq/typescript-sdk
• 使用 Cron + SDK 脚本执行计划策略
• 使用云函数（AWS Lambda、GCP Cloud Functions）执行事件驱动交易
• 使用来自 TradingView 或自定义信号提供商的 Webhook 触发器

独立自动化不受此技能的保障约束。第 12 步的模拟交易关卡涵盖交互式会话中的 MCP 工具调用；由 Cron 运行的 SDK 脚本、云函数或 Webhook 均不使用 MCP 服务，也不受该关卡约束。脚本必须在启动时自行断言使用模拟环境；如果无法确认，就必须退出——将客户端构造时的 paper=True 写为字面值，而不是从配置中读取端点；如果环境中存在实盘端点或实盘交易标志，则中止运行。实盘账户返回的响应格式与模拟账户相同，因此运行后续步骤时不会再暴露此错误。

始终：

• 在考虑使用实盘前，先在模拟环境中对任何新的自动化方案进行有意义时长的验证
• 实施熔断机制（每日最大亏损、每日最大订单数、最大持仓规模）
• 记录所有订单，并监控异常行为
• 你的 Agent 不会推荐特定的云服务提供商或基础设施方案

---

5 — 执行规则

通用规则

1. 仅限模拟交易。 此技能仅用于模拟交易。你的 Agent 必须在每次提交订单前验证模拟环境。
2. 不提供财务建议。 你的 Agent 按照你的指示执行交易。它不会推荐交易、预测价格或建议策略。
3. 默认要求确认。 除非你选择退出，否则你的 Agent 会在每笔订单提交前征求明确确认。
4. 幂等性。 每笔订单都会获得唯一的 client_order_id，以防重试时重复提交。
5. 完全透明。 MCP 工具收到的每个参数都会在预览中展示给你。
6. 安全失败。 如果任何验证步骤失败（账户检查、模拟环境验证、购买力检查），你的 Agent 都会停止并说明原因。
7. 不做推断。 你的 Agent 会严格使用你确认的参数，不会推测“你可能是这个意思”并暗中更改数值。
8. 披露限制。 如果 MCP 服务不支持你请求的功能（例如特定订单类型），你的 Agent 会告知你，而不是尝试变通处理。
9. 限制未指定范围的破坏性工具。 cancel_all_orders、close_all_positions、close_position、exercise_options_position 和 do_not_exercise_options_position 会对本会话可能从未创建的持仓执行操作，且后三种操作不可撤销。无论 confirmation_mode 如何设置，你的 Agent 都会准确列出每次调用会影响的对象，并要求明确确认；该模式仅控制订单录入。
10. 平仓属于订单录入。 平仓工具会提交市价卖单，而非删除持仓。它们受市场交易时间限制；市场关闭时，订单会排队至下一次开市时执行，成交价格未知。你的 Agent 会跟踪由此产生的订单，直至其进入终态，而不会在调用返回时就报告持仓已清空。

MCP 特定规则

11. 始终先发现工具。 调用 GetDynamicTools 查找 Alpaca 命名空间，并在调用任何工具前检查工具架构。本技能中提及的工具名称适用于当前的 v2，仅作说明，不构成约定——v2 是一次重写，v1 中没有任何工具得以保留；某个名称可能跨版本保持不变，但其架构会发生变化。请根据发现结果确认，切勿将参数架构写死。
12. 处理命名空间状态。 如果 MCP 命名空间为 "needsAuth"，请通过 mcp_auth 进行身份验证。如果为 "error" 或未找到，请告知我检查 MCP 服务配置。
13. 禁止回退到原始 HTTP。 这是 MCP 版本——如果 MCP 服务可用且正常运行，请勿回退到直接调用 HTTP API 或使用 CLI 命令。这规定了你的 Agent 如何连接 Alpaca。此规则不禁止为第 12 步的模拟环境关卡读取本地 MCP 配置，因为该操作不会访问任何 Alpaca 端点。
14. 身份验证错误不可通过更换凭据重试。 如果 MCP 工具调用因身份验证错误而失败，请告知我检查 MCP 服务配置。请勿尝试使用不同的凭据重试，也不要尝试将 API 密钥作为工具参数传入。
15. MCP 工具调用无需 required_permissions: ["all"]。 它们通过 MCP 协议运行，而非 Shell。
16. 遵守 MCP 服务边界。 如果发现的架构不包含你预期的参数（例如，期权的 position_intent），请勿自行添加——请告知我，并参考 API 文档中的变通方案。
17. 出错时重新发现工具。 如果 MCP 工具调用因意外的架构错误而失败，请使用 GetDynamicTools 重新发现工具，以防服务已更新。

特定资产类别的规则

18. 股票 — 下单前，使用资产查询工具验证标的代码是否存在且可交易。检查股票拆分、停牌或退市情况。
19. 期权 — 验证期权审批级别。通过期权合约工具确定合约，不要依赖手动拼接的 OCC 代码（例如，AAPL251219C00250000）。确认 position_intent。
20. 加密货币 — 使用斜杠分隔的交易对格式（例如，BTC/USD）。注意其支持 7×24 小时交易。分数量很常见——请确认精度。

---

6 — 输出约定

运行文件夹结构

runs/<YYYYMMDD-HHMMSS>-paper-trading-mcp/
  notes.md              # Strategy description, assumptions, risk controls
  orders.json           # All MCP order responses (create, get, list)
  order_log.csv         # Chronological log of all order actions
  positions_snapshot.json  # Position state after trades
  portfolio_summary.md  # Account and portfolio state
  review.md             # Session review and lessons learned

notes.md

包含：

• 策略说明和理由
• 所有已确认的参数
• 当前生效的风险控制措施
• 模拟环境验证详情
• 所作的任何假设
• 时间戳

orders.json

会话期间捕获的所有订单相关 MCP 响应组成的数组：

[
  {
    "action": "create",
    "timestamp": "2026-07-26T19:30:00Z",
    "request": {
      "symbol": "AAPL",
      "side": "buy",
      "qty": "10",
      "type": "limit",
      "limit_price": "185.50",
      "time_in_force": "day"
    },
    "response": {
      "id": "abc-123-def",
      "status": "new",
      "filled_qty": "0",
      "created_at": "2026-07-26T19:30:01Z"
    }
  }
]

order_log.csv

timestamp,action,order_id,client_order_id,symbol,side,qty,type,limit_price,stop_price,tif,status,filled_qty,filled_avg_price,error
2026-07-26T19:30:00Z,CREATE,abc-123-def,pt-20260726-001,AAPL,buy,10,limit,185.50,,day,new,0,,
2026-07-26T19:31:00Z,STATUS,abc-123-def,pt-20260726-001,AAPL,buy,10,limit,185.50,,day,filled,10,185.48,

positions_snapshot.json

所有交易完成后，从列出持仓的 MCP 响应中捕获。

portfolio_summary.md

以易读的方式总结会话后的账户状态、持仓和风险指标。

review.md

会话后复盘：交易内容、结果、经验教训以及后续计划。

注意：与 CLI 输出不同，MCP 响应不会自动保存为原始文件。你的 Agent 必须捕获相关响应数据，并将其明确写入 orders.json 和 order_log.csv。

---

7 — 验证和测试

提交前检查

你的 Agent 会在每次提交订单前进行验证：

检查项	方法	失败时的操作
纸面交易环境	主机 MCP 配置中的 env.ALPACA_PAPER_TRADE 未设置，或值为 true、1 或 yes。任何工具都无法读取该值——请读取配置文件。如果无法读取，则默认拒绝	停止——告知你需要重新配置
账户处于活动状态	status == "ACTIVE"	停止——账户存在问题
交易未受限	trading_blocked == false	停止——账户受限
购买力充足	buying_power >= est_notional	停止——显示购买力，并建议减少订单规模
标的可交易	使用 Get-asset 工具	停止——未找到标的或该标的不可交易
已获期权交易批准	账户期权等级	停止——告知你需要启用期权交易
已启用加密货币交易	账户加密货币状态	停止——告知你需要启用加密货币交易
订单类型有效	架构验证	停止——显示有效的订单类型
有效的 TIF	架构验证	停止——显示有效的 TIF 选项
已提供价格水平	限价单／止损单需提供限价／止损价	停止——询问缺少的价格
客户端订单 ID	生成 UUID	如果缺少，则生成

提交后检查

检查项	方法	失败时的操作
订单已接受	响应状态	报告拒绝原因
没有重复订单	client_order_id 唯一性	检测到重复时发出警告
成交价格符合预期	filled_avg_price 与 limit_price 对比	出现意外情况时发出提醒

MCP 特定验证测试

验证以下 MCP 特定故障模式：

• 未找到 MCP 命名空间
• MCP 命名空间需要身份验证
• MCP 工具架构发生变化
• MCP 服务配置为实盘环境
• MCP 工具调用出现网络错误

---

8 — 披露、安全与数据处理

披露

你的 Agent 必须包含以下披露内容：

• 每次订单预览前：

  “仅限纸面交易。不构成财务建议。过往表现不代表未来结果。”

• 讨论策略表现时：

  “纸面交易结果为模拟结果，可能无法反映真实执行、滑点或市场影响。”

• 讨论期权时：

  “期权涉及重大风险，并不适合所有投资者。纸面交易期权不会带来财务风险，但如果将测试的策略用于实盘交易，可能涉及重大风险。”

• 完整披露。 请查阅 Alpaca 的披露和协议：alpaca.markets/disclosures。

重要披露： 本材料仅用于提供信息、教育和研究，不构成投资建议、推荐、要约或买卖证券、期权、加密货币或任何其他金融产品的招揽。所有投资和交易均涉及风险，包括可能损失本金。纸面交易为模拟交易，在成交、市场影响、流动性、费用、延迟及其他因素方面可能与实盘交易有所不同。请查阅 Alpaca 的披露：https://alpaca.markets/disclosures。

安全

• 绝不进行实盘交易。 此技能会检查是否处于模拟环境，但 MCP 服务的配置最终由你负责。
• 绝不泄露 API 密钥。 密钥配置在 MCP 服务环境中，不会通过 Agent 传递。
• 绝不提供财务建议。 你的 Agent 会按你的指示执行订单并报告事实，不会推荐交易。
• 注意熔断机制。 如果你快速提交了许多订单，Agent 应指出提交频率，并询问这是否有意为之。
• 破坏性工具独立于确认模式进行限制。 关闭逐笔订单确认会加快订单提交，但绝不会免除对 close_all_positions、cancel_all_orders、close_position 或期权行权指令明确要求的“是”。
• 默认工具集包含全部工具。 ALPACA_TOOLSETS 默认启用所有功能，因此任何默认安装都可以使用清算和行权工具。如果你想让 Agent 完全无法访问这些工具，请限定此变量，而不要只依赖限制机制。

数据处理

• MCP 工具调用通过 MCP 协议发送至 Alpaca API。凭据保存在服务的配置中，绝不会作为工具参数传递，因此工具调用不会将其带入 Agent 的上下文。
• Agent 唯一会接触到存有这些凭据的文件的环节是第 12 步的模拟环境检查。此时会从该文件中读取单个字段，绝不能读取、打印或回显整个文件或整个服务条目。如果 Agent 无法只提取该字段，就应判定检查失败，而不是退而求其次读取整个文件。
• 订单数据会保存在本地运行文件夹结构中（参见 §6）。
• 除 Alpaca 外，不会向第三方服务发送交易数据。
• Agent 的对话上下文可能包含订单详情——请妥善处理聊天记录。

---

9 — 反面模式

• 绝不调用本技能中提到的工具，除非先通过发现确认其存在——这里记录的是 v2 中的名称，不保证一定可用。
• 绝不在先通过 GetDynamicTools 检查 MCP 工具的架构之前调用这些工具。
• 绝不假定 MCP 服务已配置为模拟交易，也绝不将账户响应视为此配置的证明——模拟模式取决于 ALPACA_PAPER_TRADE。
• 绝不为了检查该标志而完整读取 MCP 配置文件——同一个 env 区块中还包含 API 密钥。只提取单个字段。
• 绝不将无法识别的服务条目视为标志不存在——标志缺失时检查通过，无法确定时则应默认失败。
• 如果 MCP 服务可用，绝不退而使用直接 HTTP 调用。这是 MCP 版本。
• 绝不将 API 密钥作为 MCP 工具参数传递——服务会在内部处理身份验证。
• 绝不进行实盘交易，也绝不在账户看起来处于实盘模式时继续操作。
• 绝不在先向你展示订单预览之前提交订单。
• 绝不跳过模拟环境验证步骤。
• 绝不提供财务建议、价格预测或交易推荐。
• 绝不使用不同凭据重试身份验证错误——应告知你修复 MCP 服务配置。
• 绝不在你确认后悄悄更改订单参数。
• 绝不假定某个特定的 MCP 服务包名称或版本——应在运行时发现。
• 绝不在 MCP 工具调用中使用 required_permissions: ["all"]——调用不需要此权限。
• 绝不虚构发现的架构中不存在的 MCP 工具参数。
• 绝不将部分成交视为全部成交——始终报告剩余数量。
• 绝不在未收到指示时调用 close_all_positions 或 cancel_all_orders——这两个工具不限定范围，会操作本次会话从未创建的持仓。列出将受影响的内容，并要求明确回答“是”。
• 绝不在未获得明确确认时行权——行权和不行权指令都不可撤销。
• 绝不在平仓工具返回时就报告持仓已平——该工具提交的是卖出订单，订单可能仍在队列中或仅部分成交。

10 — 相关文件

• reference.md — MCP 工具发现模式、订单类型参考、错误处理、资产类别细节

配套技能

• alpaca-trading-paper-trading — 与实现方式无关的通用模拟交易技能
• alpaca-trading-paper-trading-cli — CLI 专用模拟交易技能