Stock Trends Market Intelligence

Stock Trends MCP 服务

用于线上公共远程 MCP 和另行提供的本地 stdio 客户端的 Stock Trends Model Context Protocol（MCP）服务。

架构边界（本服务的定位）

本仓库是一个基于前端 Stock Trends API 的轻量级 MCP 适配器。它为线上公共远程 MCP 提供支持，也支持本地 stdio；本身不具备独立的分析能力。

公共远程 MCP

将远程 MCP 客户端连接到 Streamable HTTP 端点：

https://mcp.stocktrends.com/mcp

开发者连接指南见 developer.stocktrends.com/mcp。已部署的远程接口恰好提供 19 个工具、10 个公共资源和 0 个提示词。连接和发现无需 Stock Trends 订阅 API 密钥。以下 3 个工具免费：stocktrends_estimate_workflow_cost、stocktrends_lookup_instruments 和 stocktrends_resolve_instrument。以下 16 个工具是基于 x402 V2 的付费工具：12 个 GET 工具 stocktrends_get_stim_latest、stocktrends_get_stim_history、stocktrends_get_indicators_latest、stocktrends_get_indicators_history、stocktrends_get_selections_latest、stocktrends_get_market_regime_latest、stocktrends_get_market_regime_history、stocktrends_get_breadth_sector_latest、stocktrends_get_leadership_summary_latest、stocktrends_get_screener_top、stocktrends_get_market_epoch_latest 和 stocktrends_get_market_epoch_history；以及 4 个 POST 工具 stocktrends_evaluate_symbol（POST /v1/decision/evaluate-symbol）、stocktrends_construct_portfolio（POST /v1/portfolio/construct）、stocktrends_evaluate_portfolio（POST /v1/portfolio/evaluate）和 stocktrends_compare_portfolios（POST /v1/portfolio/compare）。stocktrends_get_selections_latest 返回基础选择范围，而不是经过单独阈值筛选的已发布 ST-IM Select 列表。

对于付费远程工具，具备支付能力的 MCP 客户端会获取并授权付款。客户端会在 MCP 请求元数据中通过 x402/payment 提供该授权；适配器会将其转发给 Stock Trends API，放入上游 PAYMENT-SIGNATURE 标头，并将已确认的结算元数据作为 x402/payment-response 返回。这些 MCP 元数据字段与 API 标头各不相同。服务不会控制买家的钱包、持有私钥、签署支付授权、发起支出、重新计算 Stock Trends 智能分析，也不会执行证券交易。客户端不会仅因建立连接就获得支付能力；符合规范的 x402 REST 买家也不会自动实现这一 MCP 专用交互。不要自动重试结果不确定的付款；对于 POST 工具，即使发生分析 HTTP 错误，也可能已完成付款结算，而且待处理的质询状态绑定的是适配器的规范请求体，而不是由独立的加密签名绑定该请求体。

本地 stdio 和 Streamable HTTP 配置

本地使用需要 Node.js 20+。本地进程启动仍默认使用 stdio 传输方式，并且受到全面支持。源代码还支持显式设置 STOCKTRENDS_MCP_TRANSPORT=streamable-http，在 /mcp 提供 MCP 服务，并在 /healthz 和 /readyz 提供运行状态检查；其本地监听器默认绑定到 127.0.0.1:3000。上方部署的公共端点与此本地配置不同。官方 MCP Registry 版本 1.0.2 已发布、启用并设为最新版本；其中公布了本地 stdio npm 包，以及通过 Streamable HTTP 提供服务的远程 MCP 端点 https://mcp.stocktrends.com/mcp。

默认情况下，本地启动的 streamable-http 配置无需凭据：提供 10 个公共资源、上方列出的 3 个免费工具，且不提供提示词。该配置会拒绝已设置的 API 密钥、付费工具／执行设置，以及单独的本地 x402 中继／挑战／实时／证明转发设置。STOCKTRENDS_ENABLE_REMOTE_X402_STIM=true 是仅适用于 Streamable HTTP 的独立激活选项，用于启用面向生产环境的远程 x402 注册项：提供 3 个免费工具和 16 个 x402 付费工具（共 19 个），但不会启用基于 API 密钥的付费模式或本地挑战中继。此源代码级激活选项与已部署的公共服务不同，也不是部署指南。本地 stdio 仍可单独启用基于订阅／API 密钥的付费 REST 调用。其可选且默认关闭的 x402 模式仅用于检查／中继挑战元数据：它既不会付款，也不会转发付款证明或付款标头，不会返回付费 API 数据或产生支出。尚未实现 MPP。

权限流向只有一个方向：

Stock Trends dataset
  -> Stock Trends API
  -> published Stock Trends API responses/artifacts
  -> MCP adapter (this repository)
  -> external MCP clients/agents

MCP 适配器：

• 不会重新计算 Stock Trends 数据、ST-IM 或指标。
• 不会直接访问 Stock Trends 数据库或控制平面。
• 不会生成投资建议、研究或交易指导。
• 只会将经过审核并发布的 Stock Trends API 响应转换为 MCP 资源和工具响应。

下文介绍的公共资源和默认／免费模式无需凭据：安装、检查或使用它们都不需要 API 密钥、订阅或付款凭据。有条件启用的付费 ST-IM 执行路径是单独的、明确受限的功能，默认禁用（请参阅有条件启用的付费 ST-IM 工具）。另有一个默认关闭的 x402 配置，可提供名称相同的付费语义工具。中继与挑战标志会保留仅使用本地模拟的行为；另一个独立的实时标志可启用单请求、无密钥且有额度上限的挑战路径。两种 x402 模式都不会接受或转发证明、发送付款标头、返回付费数据、付款或产生支出。

初次使用？ 如需使用公共远程 MCP，请使用上方的端点和 Developer Portal。如需运行本地服务，请从默认／免费模式快速入门开始，然后连接本地 stdio MCP 客户端。在设置任何付费变量之前，请阅读付费模式配置和安全模型。

默认／免费模式快速入门

这是安装或检查该服务的推荐起始路径。在默认模式下，该服务：

• 不需要 API 密钥。
• 不执行任何付费操作，也不会产生支出。
• 提供 3 个免费的 MCP 工具：stocktrends_estimate_workflow_cost、stocktrends_lookup_instruments 和 stocktrends_resolve_instrument。
• 无需凭据即可使用所有公共资源。
• 注册 0 个 MCP 提示词。

设置

仅使用现有项目脚本：

git clone <repository-url>
cd stocktrends-mcp-server
npm install
npm run build

此 git clone + npm install + npm run build 流程，随后通过本地 stdio 运行编译后的 dist/server.js，仍受到全面支持，也是此仓库的主要安装渠道。此软件包也已在 npm 注册表上公开发布，名称为 @stocktrends-publications/stocktrends-mcp-server——请直接参阅下文的公开 npm 安装。第三种不同的安装方式——本地构建的 npm 软件包制品（本地 .tgz，而非从注册表安装）——也已通过跨平台验证；请参阅下文的本地软件包制品安装（自行构建的替代方案）以及跨平台软件包安装 / Stdio 验证报告。

此安装方式不需要环境变量或 .env 文件。测试默认 / 免费模式时，请勿设置 STOCKTRENDS_ENABLE_PAID_TOOLS、STOCKTRENDS_API_KEY 或 STOCKTRENDS_ENABLE_PAID_EXECUTION。

可选：npm start 可直接启动本地 stdio 服务进程，主要用于手动冒烟测试（它会等待从 stdin 接收 JSON-RPC 输入）。在通过下文的 MCP Inspector 启动服务之前，请按 Ctrl+C 停止它。

公开 npm 安装

此软件包已在 npm 注册表上公开发布，名称为 @stocktrends-publications/stocktrends-mcp-server。任何人都可以按名称安装，无需凭据，也无需克隆此仓库：

npm install @stocktrends-publications/stocktrends-mcp-server

若要固定到确切版本以便复现安装，请在上述命令后追加 @<version>（例如 @1.0.0）；省略版本即可获取最新发布版本。安装后，软件包会提供由 npm 管理的命令 shim（而非相对于检出目录的 dist/server.js 路径）——请参阅下文的连接本地 stdio MCP 客户端，其中的配置示例涵盖软件包安装后的 shim 和相对于检出目录的路径。

1.0.0 版本在发布前已与其经过冻结、离线验证的候选发布制品逐字节（SHA-256）核验；此外，也已验证无需身份验证即可按名称安装，以及 Windows MCP initialize / 仅列表握手可与已发布的软件包配合使用（参见 docs/SECURITY_MODEL.md §18 和 MCP Registry Readiness Implementation Notes）。已发布的 npm 1.0.1 制品同样是历史版本，仅提供一个免费工具；该已发布软件包的情况并不能代表当前源代码检出版本包含的三个免费工具。com.stocktrends/market-intelligence 的官方 MCP Registry 版本 1.0.2 已发布、激活且为最新版本。它公布了现有 npm 1.0.1 本地 stdio 软件包和通过 Streamable HTTP 提供的远程 MCP 端点 https://mcp.stocktrends.com/mcp；Registry 元数据版本与 npm 软件包版本有意保持不同。

本地软件包制品安装（自行构建的替代方案）

除了上文提到的公共 npm 安装方式外，也可以在本地构建并打包此仓库的软件包，生成可安装的 npm 制品，适用于 Windows 和 WSL2 Ubuntu（请参阅 跨平台软件包安装 / Stdio 验证报告）。此方式适用于使用已发布软件包的标识测试尚未发布的本地构建；常规安装无需使用此方式。

• 此制品不会保留在此仓库中——不会提交 .tgz 文件，检出仓库时也不会附带该文件。
• package.json 使用与已发布 npm 软件包相同的公共标识：带作用域的名称 @stocktrends-publications/stocktrends-mcp-server、MCP Registry 标识 mcpName com.stocktrends/market-intelligence，以及明确的公共 publishConfig（access: public，公共 npm registry）——请参阅 软件包发布配置实现说明 和 MCP Registry 就绪情况实现说明。
• 如需使用此方式，请从经过审查的检出内容自行构建制品。

从检出内容自行构建本地制品：

git clone <repository-url>
cd stocktrends-mcp-server
npm install
npm run build
npm pack

此操作会在当前目录生成 stocktrends-publications-stocktrends-mcp-server-1.0.1.tgz——经过审查的封闭制品允许列表包括 dist/**/*.js、dist/**/*.d.ts、README.md 和 LICENSE（请参阅 软件包元数据和封闭制品允许列表实现）。请将其安装到一个单独的使用方项目中（而非此检出目录）：

npm install <path-to-local-stocktrends-publications-stocktrends-mcp-server-1.0.1.tgz>

此本地制品安装方式与上文的公共 npm 安装方式通过不同渠道安装相同的、经过审查的软件包标识；除非你明确需要测试尚未发布的本地构建，否则建议使用公共 npm 安装方式。

安装后，该软件包会提供由 npm 管理的命令垫片，而非相对于检出目录的 dist/server.js 路径。在 POSIX 系统（Linux、macOS、WSL）上，它是 node_modules/.bin/stocktrends-mcp-server 中的符号链接；在 Windows 上，它是 node_modules\.bin\stocktrends-mcp-server.cmd 中生成的垫片。不要假定此可执行文件已全局安装——请从使用方项目自己的 node_modules/.bin 中解析其路径。请参阅下文的连接本地 stdio MCP 客户端，了解与检出目录示例并列的软件包安装客户端配置示例。

使用 MCP Inspector 进行检查（无需 API 密钥）

构建完成后（npm run build），将 MCP Inspector 指向已编译的 stdio 服务，并且不设置任何付费模式环境变量：

npx @modelcontextprotocol/inspector node dist/server.js

在 Inspector UI 中确认：

• 工具列表中恰好包含三个免费工具 stocktrends_estimate_workflow_cost、stocktrends_lookup_instruments 和 stocktrends_resolve_instrument；九个本地订阅/API 密钥付费工具（stocktrends_get_stim_latest、stocktrends_get_stim_history、stocktrends_get_indicators_latest、stocktrends_get_indicators_history、stocktrends_get_selections_latest、stocktrends_get_market_regime_latest、stocktrends_get_market_regime_history、stocktrends_get_breadth_sector_latest、stocktrends_get_leadership_summary_latest）不可见。
• 提示词列表为空（如果客户端提供提示词面板）。
• 公共资源（例如 stocktrends://api/openapi、stocktrends://ai/context）已列出，并且无需配置任何凭据即可读取。

此检查可确认免费/默认模式的边界，无需或触发任何付费执行。

如需查看更完整的分步 Inspector 流程——默认/免费列表、仅公开展示付费工具的列表（不执行），以及回滚检查清单——请参阅 Phase 5A MCP Inspector Validation Runbook（编写时，其中的付费工具展示界面和资源数量适用于 Phase 4 时期的三个工具界面；当前数量见本 README）。

密钥安全（免费模式）

免费/默认模式无需 API 密钥，因此本快速入门不涉及任何密钥。始终在不使用密钥的情况下测试和演示默认模式。完整的凭据处理规则——仅使用占位符，绝不提交或粘贴真实密钥——汇总在顶层的 密钥安全 部分。

连接本地 stdio MCP 客户端

本节介绍如何通过本地 stdio 将服务接入 MCP 客户端。下方各小节分别明确介绍两种安装方式：

• 仓库检出路径（先使用 npm run build 构建）：直接启动已编译的入口点，使用 command: "node" 和 args: ["<absolute-path-to-checkout>/dist/server.js"]，其中 <absolute-path-to-checkout> 是你计算机上此仓库的绝对路径。
• 本地软件包构件路径（见上文本地软件包构件安装）：从 <path-to-consumer-project> 解析通过 npm 安装的命令垫片；该路径是你运行 npm install <path-to-local-...-1.0.1.tgz>（或 npm install @stocktrends-publications/stocktrends-mcp-server——参见公共 npm 安装`）的另一个独立项目的绝对路径，而非此仓库检出目录，也不是全局安装。

本节中的每个主要示例都使用免费模式：不设置任何 STOCKTRENDS_* 变量，不配置 API 密钥，也不会产生任何费用。向客户端配置文件添加任何付费变量之前，请阅读密钥安全。

A. Claude Desktop

免费模式 mcpServers 条目（无 env 块，默认无需凭据）：

{
  "mcpServers": {
    "stocktrends": {
      "command": "node",
      "args": ["<absolute-path-to-checkout>/dist/server.js"]
    }
  }
}

Windows JSON 路径必须使用双反斜杠（"C:\\Users\\you\\stocktrends-mcp-server\\dist\\server.js"）或正斜杠（"C:/Users/you/stocktrends-mcp-server/dist/server.js"）；单个反斜杠不是有效的 JSON。

Claude Desktop 配置文件的位置取决于客户端版本；截至撰写本文时，位置如下：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

请先对照当前安装的 Claude Desktop 版本的文档核实这些路径再使用，因为不同客户端版本的文件位置和架构可能有所变化。

已安装软件包的变体（本地构件路径，免费模式）。 使用通过 npm 安装的命令 shim，而不是相对于检出目录的路径：

{
  "mcpServers": {
    "stocktrends": {
      "command": "<path-to-consumer-project>/node_modules/.bin/stocktrends-mcp-server"
    }
  }
}

Windows 对应写法（生成的 .cmd shim）：

{
  "mcpServers": {
    "stocktrends": {
      "command": "<path-to-consumer-project>\\node_modules\\.bin\\stocktrends-mcp-server.cmd"
    }
  }
}

<path-to-consumer-project> 是你运行 npm install <path-to-local-stocktrends-publications-stocktrends-mcp-server-1.0.1.tgz>（或 npm install @stocktrends-publications/stocktrends-mcp-server）的独立项目的绝对路径，绝不能是此仓库的检出目录，也不能是全局安装路径。

可选的付费工具暴露变体（仅暴露，不执行）。 这会将付费工具的定义添加到客户端的工具列表中；它不会授权或执行任何付费 API 调用：

{
  "mcpServers": {
    "stocktrends": {
      "command": "node",
      "args": ["<absolute-path-to-checkout>/dist/server.js"],
      "env": {
        "STOCKTRENDS_ENABLE_PAID_TOOLS": "true",
        "STOCKTRENDS_API_KEY": "<your-api-key>"
      }
    }
  }
}

暴露（STOCKTRENDS_ENABLE_PAID_TOOLS + 密钥）和执行（单独的 STOCKTRENDS_ENABLE_PAID_EXECUTION 标志，以及强制性的定价预检、非零上限和覆盖所需费用的预算——参见付费模式配置）是两道独立的关卡：此变体未设置执行，因此仅启用暴露绝不会发送请求或产生费用。付费执行的资格检查清单请参见Phase 5A 操作安全与发布检查清单 §4；该清单并非实时执行操作手册。

持久化配置的凭据警告。 Claude Desktop 配置文件是明文文件，并会在重启后继续保存在磁盘上。如果你为有意进行且由操作人员监督的会话在此处填写真实 API 密钥，请在会话结束后立即将其删除，并恢复上面的免费模式条目；不要将真实密钥留在客户端配置文件中。

B. Claude Code

边界说明： Claude Code 是一个 Agent 型客户端，Phase 5D 的批准不适用于 Agent 自主执行付费操作。因此，Claude Code 的文档化用法仅限于免费模式，其中全部三个工具都无需凭据，也不可能产生费用。付费暴露/执行仍是独立的、由操作人员在 shell 中监督的流程，具体参见付费模式配置和上文所述的资格检查清单；本文特意不提供 Claude Code 的配置示例。

使用 Claude Code CLI 在本地注册服务：

claude mcp add --transport stdio stocktrends -- node <absolute-path-to-checkout>/dist/server.js

这会注册一个没有 env 条目的免费模式 stdio 服务。等效地，项目级 .mcp.json 条目的结构相同（带有 command 和 args 且没有 type/url 字段的条目会被视为 stdio 服务）：

{
  "mcpServers": {
    "stocktrends": {
      "command": "node",
      "args": ["<absolute-path-to-checkout>/dist/server.js"]
    }
  }
}

已安装软件包的变体（本地构件路径，免费模式，POSIX）：

claude mcp add --transport stdio stocktrends -- <path-to-consumer-project>/node_modules/.bin/stocktrends-mcp-server

已安装软件包的变体（本地构件路径，免费模式，Windows）：

claude mcp add --transport stdio stocktrends -- <path-to-consumer-project>\node_modules\.bin\stocktrends-mcp-server.cmd

<path-to-consumer-project> 是你运行 npm install <path-to-local-stocktrends-publications-stocktrends-mcp-server-1.0.1.tgz>（或 npm install @stocktrends-publications/stocktrends-mcp-server）的独立项目的绝对路径，绝不能是此仓库的检出目录，也不能是全局安装路径。

C. 通用 MCP stdio 客户端

任何支持本地 stdio 服务的 MCP 客户端都可以使用这种与客户端无关的配置：

{
  "command": "node",
  "args": ["<absolute-path-to-checkout>/dist/server.js"],
  "env": {}
}

通过软件包安装的变体（本地制品路径，免费模式）。 POSIX：

{
  "command": "<path-to-consumer-project>/node_modules/.bin/stocktrends-mcp-server",
  "env": {}
}

Windows（生成的 .cmd 垫片）：

{
  "command": "<path-to-consumer-project>\\node_modules\\.bin\\stocktrends-mcp-server.cmd",
  "env": {}
}

<path-to-consumer-project> 是你运行 npm install <path-to-local-stocktrends-publications-stocktrends-mcp-server-1.0.1.tgz>（或 npm install @stocktrends-publications/stocktrends-mcp-server）的独立项目的绝对路径——绝不能是此仓库的检出目录，也不能是全局安装路径。

可选的付费工具暴露变体（规则与上文的 Claude Desktop 相同——仅暴露工具，不包含执行标志）：

{
  "command": "node",
  "args": ["<absolute-path-to-checkout>/dist/server.js"],
  "env": {
    "STOCKTRENDS_ENABLE_PAID_TOOLS": "true",
    "STOCKTRENDS_API_KEY": "<your-api-key>"
  }
}

暴露不等于执行：只有另外将 STOCKTRENDS_ENABLE_PAID_EXECUTION 设为 true，并且通过强制定价预检、非零本地上限和覆盖相应费用的预算上限检查后，才会发出请求并产生费用（请参阅付费模式配置）。此处不会将付费执行写成可随意照做的操作指南；请将其视为资格检查清单，而不是可直接复制粘贴的配方。

D. MCP Inspector 作为诊断参考

MCP Inspector 仍然是用于确认服务的工具、资源和提示词范围的实用诊断／运维工具——请参阅上文的使用 MCP Inspector 检查——但它并非唯一的安装途径，也不是主要途径。日常使用时，请连接上文 A–C 中的某个客户端。Phase 5A MCP Inspector 验证操作手册记录了更完整的 Inspector 操作流程；其中付费工具暴露范围和资源数量在编写时对 Phase 4 时期的三工具范围是正确的，作为历史记录仍然准确，但当前数量请参阅本 README。

付费模式配置

付费工具默认禁用。本节内容并非安装、检查或以默认／免费模式使用服务所必需。本节说明如何暴露付费 ST-IM 工具，以及如何单独设置付费执行的门控。在配置任何付费变量前，请先阅读本节。付费模式的安全策略由 docs/SECURITY_MODEL.md 和 docs/PHASE5A_OPERATIONAL_HARDENING_DESIGN_MEMO.md 规定。

付费工具暴露与付费执行是两个独立的门控。 启用暴露本身绝不会执行付费调用。

付费标志的解析规则严格： 只有字面字符串 true 才会启用 STOCKTRENDS_ENABLE_PAID_TOOLS 或 STOCKTRENDS_ENABLE_PAID_EXECUTION。值 false、0、no 和 off 会禁用它们。1、yes 或 on 等其他值会导致启动失败，并返回 invalid_config。执行标志名为 STOCKTRENDS_ENABLE_PAID_EXECUTION；STOCKTRENDS_ALLOW_PAID_EXECUTION 不是受识别的变量，设置它不会产生任何效果。

暴露付费工具必须同时满足以下条件：

• 已配置 STOCKTRENDS_ENABLE_PAID_TOOLS=true
• 已配置 STOCKTRENDS_API_KEY

同时满足这两项后，服务还会注册两项配对的付费 ST-IM 工具定义、两项配对的付费指标工具定义、基础选项工具定义，以及四项市场上下文工具定义，因此暴露的工具集合总数恰好为十二项：

• stocktrends_estimate_workflow_cost — 无需凭据的规划工具（始终可用）
• stocktrends_lookup_instruments — 无需凭据的标的发现工具（始终可用）
• stocktrends_resolve_instrument — 无需凭据的标的解析工具（始终可用）
• stocktrends_get_stim_latest — 付费 ST-IM 工具定义
• stocktrends_get_stim_history — 付费 ST-IM 工具定义
• stocktrends_get_indicators_latest — 付费指标工具定义
• stocktrends_get_indicators_history — 付费指标工具定义
• stocktrends_get_selections_latest — 付费基础 ST-IM 选股范围工具定义
• stocktrends_get_market_regime_latest — 付费市场背景工具定义（市场状态）
• stocktrends_get_market_regime_history — 付费市场背景工具定义（市场状态）
• stocktrends_get_breadth_sector_latest — 付费市场背景工具定义（广度）
• stocktrends_get_leadership_summary_latest — 付费市场背景工具定义（领涨情况）

开放工具不会改变三个免费工具，也不会发送任何 API 密钥。它只会让 MCP 客户端看到九个付费工具定义。付费指标使用的内部标的解析器是一个无需凭据的辅助程序，与单独注册的公开工具 stocktrends_lookup_instruments 和 stocktrends_resolve_instrument 不同。因此，默认/免费界面仍只有三个工具。

执行付费操作还必须满足以下所有条件：

• STOCKTRENDS_ENABLE_PAID_EXECUTION=true — 与开放标志不同的独立运行时标志。
• 必须进行定价预检解析（STOCKTRENDS_REQUIRE_PRICING_PREFLIGHT 保持为 true）。
• 显式设置非零本地上限（STOCKTRENDS_MAX_PAID_CALLS_PER_SESSION 和 STOCKTRENDS_MAX_PAID_CALLS_PER_TOOL）。
• 设置足以覆盖非零费用的预算上限（STOCKTRENDS_MAX_STC_PER_SESSION，以及适用美元费用时的 STOCKTRENDS_MAX_USD_PER_SESSION）。

启用执行会改变调用行为，而非工具数量。启用执行且所有门槛均通过时，调用付费 ST-IM、指标、选股或市场背景工具可能会发送一条经授权的请求；未启用执行，或任一解析/限制/上限/预检门槛未通过时，同一工具会安全失败，不发送请求，也不带认证标头。

启用开放后，本地订阅/API 密钥付费界面包含十二个工具：三个免费工具，以及 stocktrends_get_stim_latest、stocktrends_get_stim_history、stocktrends_get_indicators_latest、stocktrends_get_indicators_history、stocktrends_get_selections_latest、stocktrends_get_market_regime_latest、stocktrends_get_market_regime_history、stocktrends_get_breadth_sector_latest 和 stocktrends_get_leadership_summary_latest。开放标志和执行标志会改变可见性和行为，但不会改变本地付费界面的工具数量。

暴露与执行

概念	含义
暴露	九个付费工具定义（stocktrends_get_stim_latest、stocktrends_get_stim_history、stocktrends_get_indicators_latest、stocktrends_get_indicators_history、stocktrends_get_selections_latest、stocktrends_get_market_regime_latest、stocktrends_get_market_regime_history、stocktrends_get_breadth_sector_latest、stocktrends_get_leadership_summary_latest）对 MCP 客户端可见。
执行	调用付费工具且通过相应关卡时，可能会发送实际获授权的 API 请求至经批准的 ST-IM、指标、基础选股或市场上下文端点（ST-IM/指标还要求解析出规范的标的身份；选股和市场上下文还会强制执行有界且始终发送的限制）。

• 执行关卡有意比暴露关卡更严格。让工具定义可见，要比授权实际计费调用容易得多。
• 如果未启用执行，或限额／定价预检未通过，付费工具会默认拒绝：不会发送请求，不会附加 X-API-Key，并会返回确定且不含机密信息的拒绝结果。
• 在所有模式下，公共资源和 stocktrends_estimate_workflow_cost 均无需凭证。它们绝不会发送 API 密钥，也不受暴露或执行标记影响。

启用付费工具暴露（仅暴露，不执行）

以下示例会暴露付费工具定义，以便操作员确认工具总数为 12。此操作仅用于工具暴露：不会启用付费执行，也不得用于执行实时付费调用。

# Exposure only: makes the nine paid ST-IM, indicators, base-selections, and
# market-context tool definitions visible.
# This does NOT authorize or perform any paid API call.
export STOCKTRENDS_ENABLE_PAID_TOOLS=true
export STOCKTRENDS_API_KEY="<your-api-key>"        # placeholder — never paste a real key
# Execution stays disabled (its default). Do not set this to true just to test exposure.
export STOCKTRENDS_ENABLE_PAID_EXECUTION=false

PowerShell 等效命令（Windows）：

# Exposure only: makes the nine paid ST-IM, indicators, base-selections, and
# market-context tool definitions visible.
# This does NOT authorize or perform any paid API call.
$env:STOCKTRENDS_ENABLE_PAID_TOOLS = "true"
$env:STOCKTRENDS_API_KEY = "<your-api-key>"        # placeholder — never paste a real key
# Execution stays disabled (its default). Do not set this to true just to test exposure.
$env:STOCKTRENDS_ENABLE_PAID_EXECUTION = "false"

会话结束后，请清除这些变量，不要让它们继续处于已设置状态：

# POSIX
unset STOCKTRENDS_ENABLE_PAID_TOOLS STOCKTRENDS_API_KEY STOCKTRENDS_ENABLE_PAID_EXECUTION

# PowerShell
Remove-Item Env:STOCKTRENDS_ENABLE_PAID_TOOLS -ErrorAction SilentlyContinue
Remove-Item Env:STOCKTRENDS_API_KEY -ErrorAction SilentlyContinue
Remove-Item Env:STOCKTRENDS_ENABLE_PAID_EXECUTION -ErrorAction SilentlyContinue

若要确认父级 shell 中没有任何 STOCKTRENDS_* 变量仍处于已设置状态，同时始终不打印任何值（仅显示名称）：

# PowerShell — names only, never values
Get-ChildItem Env: | Where-Object { $_.Name -like 'STOCKTRENDS_*' } | Select-Object -ExpandProperty Name

# POSIX — names only, never values
env | grep '^STOCKTRENDS_' | cut -d= -f1

切勿对任何付费变量使用 setx 或系统／用户级持久环境变量，尤其是 STOCKTRENDS_API_KEY。 setx 会将值写入 Windows 注册表，并在所有后续 shell 会话和重启后持续生效，破坏按会话管理凭证的规范；请优先使用上文按会话设置的 $env:/export 形式，并在会话结束时清除变量。

使用此配置时，MCP 客户端会准确列出 12 个工具：3 个免费工具，以及 9 个本地订阅／API 密钥付费工具定义。由于执行标记为 false，且未配置非零限额或预算上限，因此不会发送付费请求。这样就足以在不产生任何费用的情况下验证付费暴露范围。关于如何在 MCP Inspector 下逐步确认已暴露的付费工具范围（仍不执行任何实时付费调用），请参阅 Phase 5A MCP Inspector 验证操作手册（其中的数量反映 Phase 4 时期的 3 工具范围；当前数量请参阅本 README）。

付费执行还需要满足上述其他关卡（执行标记、强制预检、明确设置非零限额，以及覆盖相应费用的预算上限）。此处有意不提供逐步实时执行操作手册。如需了解任何单独获授权的实时运行前必须满足的操作员先决条件（仅作概念性说明，不含实时调用命令），请参阅 Phase 5A 操作员安全与发布检查清单。请勿仅为测试安装而启用付费执行——在免费模式和已暴露付费工具但未启用执行的模式下，都可以充分演示安装和工具列表验证。

x402 挑战中继标志

PR #69 通过现有的九个付费语义工具名称接入了 PR #66 中的模拟挑战辅助程序。x402 中继默认关闭，且仅使用模拟模式。它不会添加新的工具名称、提示词或资源；不会发送网络请求或解析器请求；不使用 API 密钥；不接受或转发任何证明；不构造任何付款标头；不返回任何付费 API 数据；也不会创建任何付款或支出。

设置 STOCKTRENDS_ENABLE_X402_RELAY=true 后，服务会列出与 API 密钥付费功能启用时相同的 12 个工具：三个免费工具以及现有的九个付费语义工具。如果挑战执行标志未设置或处于关闭状态，这九个工具的调用都会在本地安全失败，并返回 x402_challenge_unavailable。如果中继标志和挑战执行标志都为字面值 true，每个付费语义工具都会返回确定性的本地纯结构 payment_required 元数据。在此模式下，依赖标的的四个工具必须使用规范的 symbol_exchange，因此不会执行任何标的查询或解析流程。同一服务器会话中重复发起完全相同的挑战调用时，将安全失败并返回 x402_repeated_challenge_call。

x402 标志包括 STOCKTRENDS_ENABLE_X402_RELAY、STOCKTRENDS_ENABLE_X402_CHALLENGE_EXECUTION 和 STOCKTRENDS_ENABLE_X402_LIVE_CHALLENGE_RELAY，以及不受支持的 STOCKTRENDS_ENABLE_X402_PROOF_FORWARDING。这些标志默认均为关闭状态。只有字面值 true 才会启用前两个标志；false、0、no 和 off 会禁用它们；1、yes 或 on 等含义不明确的真值会导致启动失败，并返回 invalid_config。此版本不支持转发证明：将 STOCKTRENDS_ENABLE_X402_PROOF_FORWARDING=true 会导致安全失败。启用 x402 中继配置时，不能同时设置 STOCKTRENDS_ENABLE_PAID_TOOLS；混合模式会在读取任何 API 密钥之前导致启动失败。x402 模式与 API 密钥模式之间不存在回退机制。

实时标志也采用严格的字面值 true 解析，并要求中继和挑战标志均为字面值 true；否则启动会失败，并返回 invalid_config / x402_live_challenge_not_enabled。三个标志全部为 true 时，在规范输入、证明、重复调用、单工具和单会话各项检查均通过后，允许列表中的语义工具调用可以向对应的 Stock Trends API 路由恰好发送一次不带密钥的 GET 请求。该请求使用经过审核的 API 源站，采用手动重定向、忽略凭据、不带请求正文，且只包含安全的 Accept / User-Agent 标头。请求不会发送 API 密钥、授权标头、付款标头、证明或 Cookie，也不会执行解析器、目录、资源、重试或回退调用。

实时结果仅返回经批准的状态、路由、方法、标头名称、顶层键和字段类别元数据。条件性挑战值（包括 x-request-id 的值）不会出现在 structuredContent 或文本中。每个会话中，每个工具最多预留一次实时挑战，总计最多预留三次；即使网络、状态或结构检查失败，该预留仍会被视为已消耗，以防止重试循环。状态保存在内存中，并在服务器重启时重置。

请参阅 Phase 5F x402 Public Mock Wiring Implementation Notes 和 Phase 5F x402 Live No-Key Challenge Implementation Notes。

密钥安全

这些规则适用于涉及此服务的所有示例、截图、录屏和共享材料。

• 绝不提交 API 密钥。 此仓库、已纳入版本控制的配置或任何已提交文件中都不得包含密钥。
• 绝不将真实 API 密钥粘贴到 README 示例、截图、终端录屏、共享聊天或问题报告中。只能使用占位符（例如 <your-api-key>）。
• 免费／默认模式无需密钥。 无需 API 密钥即可完全运行，快速入门必须在不使用密钥的情况下演示。
• 公共资源和 stocktrends_estimate_workflow_cost 规划工具绝不会发送 API 密钥。无论付费配置如何，它们都无需凭据。
• 本地检查时，优先使用按会话设置的 Shell 环境变量（例如在单个 Shell 中运行 export STOCKTRENDS_API_KEY=<your-api-key>），而不要将密钥写入持久化、整台机器通用或已纳入版本控制的位置。
• 启用付费工具时，API 密钥只会作为 X-API-Key 标头发送到获准的付费 ST-IM、指标、基础 selections/latest 和市场环境（market/regime/latest、market/regime/history、breadth/sector/latest、leadership/summary/latest）端点，并且只有在通过所有门禁后才会发送。无需凭据的工具解析器（/v1/instruments/lookup、/v1/instruments/resolve）、定价目录和 stocktrends://leadership/definitions 公共资源绝不会收到该密钥。不会回退到 Authorization: Bearer。
• 密钥绝不会被记录，也不会出现在错误、拒绝响应或返回的数据中。

发布前，请运行第 5A 阶段操作安全与发布检查清单中的手动密钥安全扫描，以确认没有提交真实密钥、已填入凭据的标头或包含密钥的材料。允许使用 <your-api-key> 这样的占位符；看起来像真实密钥的内容则不允许。

当前状态

此仓库为已部署的公共远程 MCP 提供支持，通过 Streamable HTTP 运行，地址为 https://mcp.stocktrends.com/mcp：包含 19 个工具（三个免费工具和 16 个 x402 V2 付费工具）、十个资源和零个提示词。付费远程接口包含 12 个 GET 工具和四个分析型 POST 工具；它使用 MCP 专用的 x402/payment 和 x402/payment-response 元数据交换，并通过 PAYMENT-SIGNATURE 将已接受的授权转发到上游。本地 stdio 仍是本地进程启动的默认方式，支持免费／默认接口、单独设有门禁的订阅／API 密钥付费工具，以及可选的默认关闭的 x402 挑战检查／中继（不会付款、转发凭证、发送付款标头、获取付费数据或产生支出）。

包含：

• 提供公开的 Streamable HTTP 远程 MCP，以及单独支持的本地 stdio 传输（本地进程启动的默认方式）。
• 提供公开的 Stock Trends API 资源、三个免费远程 MCP 工具，以及已部署的 16 个 x402 V2 付费远程 MCP 工具。
• 按请求获取数据；启动时无需获取 API 数据。
• 三个免费远程 MCP 工具：stocktrends_estimate_workflow_cost、stocktrends_lookup_instruments 和 stocktrends_resolve_instrument。
• 16 个已部署的 x402 V2 付费远程 MCP 工具：列于 公开远程 MCP 中的 12 个 GET 工具和 4 个分析类 POST 工具。客户端通过 x402/payment 提供支付授权；服务仅将其转发至加入允许列表的 Stock Trends API 端点，作为 PAYMENT-SIGNATURE，并通过 x402/payment-response 报告已确认的结算；服务既不持有买方钱包，也不使用买方钱包签名。
• 有条件提供成对的付费 ST-IM 工具（stocktrends_get_stim_latest、stocktrends_get_stim_history）、成对的付费指标工具（stocktrends_get_indicators_latest、stocktrends_get_indicators_history）、基础 ST-IM 选取范围工具（stocktrends_get_selections_latest），以及四个市场背景工具（stocktrends_get_market_regime_latest、stocktrends_get_market_regime_history、stocktrends_get_breadth_sector_latest、stocktrends_get_leadership_summary_latest）；仅在显式启用付费模式并提供 API 密钥时才会公开（三个免费工具加九个付费工具，共 12 个工具）。实时订阅/API 密钥执行（仅使用 X-API-Key）只有在双重门控策略下才会运行：启用付费工具的标志、API 密钥、独立的 STOCKTRENDS_ENABLE_PAID_EXECUTION 运行时标志、权威静态定价/预检、按工具系列进行目录协调，以及非零本地限额（并配有覆盖该额度的预算）；对于指标工具，只有在不使用凭证的情况下将裸符号/原始符号解析为唯一规范身份后才会运行；对于选取范围和市场背景工具，则必须遵守列表格式的广泛扫描/限额安全控制（始终发送有界限额、仅获取一次、不进行批量请求/重试、拒绝重复的相同调用循环）；否则将安全失败，不发送请求，也不发送认证/支付标头。请参阅有条件提供的付费 ST-IM 工具（订阅/API 密钥执行）、有条件提供的付费指标工具（订阅/API 密钥执行）、有条件提供的付费选取范围工具（订阅/API 密钥执行）和有条件提供的付费市场背景工具（订阅/API 密钥执行）章节。
• 没有 MCP 提示词。
• 默认/公开接口无需 API 密钥。
• 默认关闭的公开模拟 x402 接线通过现有的九个付费语义工具名称实现，仅返回本地结构校验挑战结果，并执行规范符号校验和重复相同调用拒绝；不包含网络/证明/支付/支出路径。
• 默认关闭的实时无密钥 x402 挑战中继通过相同的九个语义工具实现；只有在启用独立的第三个标志和两个前置标志后才会开启。每个工具最多一次请求，每个服务会话最多三次请求；中继仅转发结构元数据，不涉及 API 密钥、证明、支付标头、支付、支出、付费输出、解析器、重试或回退路径。
• 内部付费模式配置、主机端强制策略、端点/工具允许列表关联、仅使用 X-API-Key 构建认证信息、脱敏、静态端点定价策略、基于内存的每会话支出限额、单次尝试且不重试的获取，以及仅模拟验证。

排除项：

• 在自动化测试中验证实时 API（代码中存在执行路径，但仅通过模拟进行测试；实时验证需要在合并后由操作员另行授权）。
• 钱包托管、钱包配置、私钥处理、支付签名、自主消费、自动重试支付、OAuth 和 MPP。已部署的远程 MCP 会转发客户端提供的 x402 授权并处理已确认的结算；其单独受门控的本地 stdio x402 中继仅支持质询，不使用密钥、不转发证明、不支付、不消费，且仅提供形状元数据。
• Authorization: Bearer 回退。
• 客户 API 密钥转发，以及远程 OAuth／订阅者身份验证。已部署的远程 MCP 的 x402 付费执行由支付客户端发起，并非 API 密钥或钱包托管服务。
• 数据库或控制平面访问。
• 从 /v1/ai/tools 或 /v1/workflows 动态注册 MCP。
• Intelligence Agent 重新计算、生成指导、生成研究或并行推理层。

本地开发

在专用分支或工作树中操作。不要直接修改 main。

切勿在此代码库中存储 API 密钥、Bearer 令牌、支付标头、钱包资料、数据库凭据或其他机密信息。

安装依赖项：

npm install

运行验证：

npm run typecheck
npm test
npm run build

启动已构建的 stdio MCP 服务：

npm run build
npm start

开发期间在本地执行 TypeScript：

npm run dev

不要在终端中直接运行 stdio 服务并期待看到人类可读的输出。stdout 专用于 MCP JSON-RPC 消息。

环境变量

所有变量均为可选项；默认设置会使服务保持免费模式。影响范围列说明变量适用于所有模式、付费工具的暴露，还是付费执行（参见付费模式配置）。只有 STOCKTRENDS_API_KEY 是机密信息。

变量	影响范围	默认值	行为与机密安全说明
STOCKTRENDS_API_BASE_URL	所有模式	https://api.stocktrends.com	必须是获准的 Stock Trends HTTPS 源。不是机密。
STOCKTRENDS_MCP_TRANSPORT	所有模式	stdio	可接受的值为 stdio 和 streamable-http；stdio 是本地启动默认值。默认情况下，streamable-http 会公开 10 个资源和 3 个免费工具，并拒绝本地 API 密钥付费模式及本地 x402 中继／质询／证明转发设置。只有启用独立的 STOCKTRENDS_ENABLE_REMOTE_X402_STIM=true 后，才能改为托管 19 个工具的生产式 Remote x402 界面。不是机密。
STOCKTRENDS_MCP_HTTP_BIND_ADDRESS	仅限 Streamable HTTP	127.0.0.1	非空主机名或 IP 地址，不得包含空白字符。绑定到非环回地址时，必须设置 STOCKTRENDS_MCP_HTTP_ALLOWED_HOSTS。不是机密。
STOCKTRENDS_MCP_HTTP_PORT	仅限 Streamable HTTP	3000	介于 1 和 65535 之间的整数。不是机密。
STOCKTRENDS_MCP_HTTP_ALLOWED_HOSTS	仅限 Streamable HTTP	无	可选的逗号分隔非通配符主机名允许列表；绑定到非环回地址时必须设置。不是机密。
STOCKTRENDS_MCP_HTTP_ALLOWED_ORIGINS	仅限 Streamable HTTP	无	用于 Origin 验证的可选逗号分隔非通配符允许列表；未设置时，如果已配置主机允许列表，HTTP 服务会使用该列表，否则会验证环回 Origin。不是机密。
STOCKTRENDS_MCP_LOG_LEVEL	所有模式	warn	普通日志写入 stderr，绝不写入 stdout。不是机密。
STOCKTRENDS_ENABLE_PAID_TOOLS	付费工具公开	false	公开标志。设置为 true 且已配置 API 密钥时，会公开两项配对的付费 ST-IM 工具定义、两项配对的付费指标工具定义、基础 selections 工具定义，以及 4 项市场上下文工具定义（3 个免费工具加 9 个付费工具，共 12 个；内部解析器辅助工具与两项公开发现工具不同）。不会自行执行——执行还需要启用 STOCKTRENDS_ENABLE_PAID_EXECUTION。不是机密。
STOCKTRENDS_API_KEY	付费工具公开与执行	无	机密——所有文档、示例、截图和共享资料中都应使用占位符（<your-api-key>）；切勿提交或粘贴真实值。 仅当 STOCKTRENDS_ENABLE_PAID_TOOLS=true 时读取；仅保留在进程本地。只有在所有关卡均通过后，才会作为 X-API-Key 标头发送到获准源及允许列表中的付费 ST-IM、指标、基础 selections/latest 和市场上下文端点（不会回退到 Authorization: Bearer）。不会发送到公共资源（包括 stocktrends://leadership/definitions）、成本估算规划工具、定价目录或无需凭据的标的解析器；不会记录日志、暴露在错误／拒绝信息中或包含在返回数据中。
STOCKTRENDS_ENABLE_PAID_EXECUTION	付费执行	false	执行标志，与公开标志不同。对 GET /v1/stim/latest、GET /v1/stim/history、GET /v1/indicators/latest、GET /v1/indicators/history、GET /v1/selections/latest、GET /v1/market/regime/latest、GET /v1/market/regime/history、GET /v1/breadth/sector/latest 和 GET /v1/leadership/summary/latest 发起实时订阅／API 密钥调用，要求此项为 true，并且启用付费工具标志、配置 API 密钥、通过权威静态定价／预检、完成按类别的目录核对，并设置至少 1 项非零调用上限及足以覆盖非零费用的预算上限（指标还需要安全解析出的规范标识；selections 和市场上下文还会执行有界的始终发送限制，并防护重复的相同调用循环）。单独启用此标志（未启用工具标志／未配置密钥）不会公开或执行任何内容。不是机密。
STOCKTRENDS_ENABLE_X402_RELAY	x402 工具公开	false	只有字面值 true 才会在无 API 密钥的情况下公开现有 9 个付费语义工具名称（3 个免费工具加 9 个中继工具，共 12 个）。false、0、no 和 off 会禁用此功能；含义不明确的真值会导致启动失败。除非同时启用质询标志，否则调用会安全地失败。不可与 STOCKTRENDS_ENABLE_PAID_TOOLS 混用。不是机密。
STOCKTRENDS_ENABLE_REMOTE_X402_STIM	生产式 Remote x402 激活	false	仅适用于 STOCKTRENDS_MCP_TRANSPORT=streamable-http；字面值 true 会启用 3 个免费工具和 16 个 x402 V2 付费工具（共 19 个）。它不同于本地 API 密钥付费模式和本地质询中继；这些模式仍与此 HTTP 配置不兼容。此设置不会赋予服务钱包托管权限、私钥或支付签名权限。不是机密。
STOCKTRENDS_ENABLE_X402_CHALLENGE_EXECUTION	x402 质询行为	false	仅在 STOCKTRENDS_ENABLE_X402_RELAY=true 时可用。字面值 true 会保留确定性的本地 PR #64 仅结构模拟结果，除非同时启用独立的实时标志。不会执行解析器查询、身份验证、证明、支付或支出。不是机密。
STOCKTRENDS_ENABLE_X402_LIVE_CHALLENGE_RELAY	实时无密钥质询请求	false	只有字面值 true 才会启用；要求中继和质询标志都为字面值 true，否则启动会因 x402_live_challenge_not_enabled 失败。每次已接受的调用最多向精确的允许列表路由发起一次无密钥 GET，每个工具最多 1 次，每个服务会话总计最多 3 次。手动处理重定向、不携带凭据、无请求正文、无 API 密钥／身份验证／支付／证明标头、无解析器／目录／资源附带调用、无重试／回退、无付费数据、支付或支出。省略条件式质询值。不是机密。
STOCKTRENDS_ENABLE_X402_PROOF_FORWARDING	不支持的 x402 证明转发	false	仍不支持证明转发。接受关闭值；true 会以 invalid_config／未启用证明转发的状态导致启动失败。不会添加证明架构、存储、转发、支付标头或验证。不是机密。
STOCKTRENDS_REQUIRE_PRICING_PREFLIGHT	付费执行	true	定价／预检状态。必须执行预检；将其设为 false 会拒绝付费执行（安全地失败），而不是降低要求。不是机密。
STOCKTRENDS_MAX_PAID_CALLS_PER_SESSION	付费执行	0	每个会话的付费调用上限。0 会拒绝所有付费调用；实时执行要求显式设置非零值。按会话存储在内存中；重启后重置。不是机密。
STOCKTRENDS_MAX_PAID_CALLS_PER_TOOL	付费执行	0	每个工具的付费调用上限。0 会拒绝调用；必须显式设置非零值。按会话存储在内存中；重启后重置。不是机密。
STOCKTRENDS_MAX_STC_PER_SESSION	付费执行	无	STC 预算上限。若 STC 费用非零但未设置 STC 上限，则会拒绝调用。由于 ST-IM 规则的费用非零，实际上必须设置预算上限。不是机密。
STOCKTRENDS_MAX_USD_PER_SESSION	付费执行	无	USD 预算上限。若 USD 费用非零但未设置 USD 上限，则会拒绝调用。不是机密。

公共资源

服务注册了以下资源：

MCP 资源 URI	后端端点
stocktrends://api/openapi	GET /v1/openapi.json
stocktrends://ai/context	GET /v1/ai/context
stocktrends://ai/tools	GET /v1/ai/tools
stocktrends://workflows	GET /v1/workflows
stocktrends://methodology/stim	GET /v1/meta/stim
stocktrends://methodology/indicators	GET /v1/meta/indicators
stocktrends://methodology/inference	GET /v1/meta/inference
stocktrends://pricing/catalog	GET /v1/pricing/catalog
stocktrends://proof/market-edge	GET /v1/ai/proof/market-edge
stocktrends://leadership/definitions	GET /v1/leadership/definitions

所有十个资源在任何模式下均无需凭证（按请求获取，永远不需要 API 密钥）。stocktrends://leadership/definitions 提供领导力指标和分类定义（通过无需凭证的读取验证为公开且零成本），是付费领导力摘要工具的解释性配套资源；它永远不需要密钥、不在付费允许列表中，也不会作为付费定价规则的镜像。

候选情报资源在通过无需密钥的公开验证前仍不予开放：

排除的候选端点	原因
GET /v1/intelligence/discovery	2026-07-07 的 Phase 1 和 Phase 2 检查中，无需密钥的验证返回了 503 application/json。
GET /v1/intelligence/editorial/latest/preview	2026-07-07 的 Phase 1 和 Phase 2 检查中，无需密钥的验证返回了 503 application/json。

公共规划工具

当前源代码头部的本地默认/免费模式注册了三个公共/免费 MCP 工具。工作流规划工具如下：

MCP 工具	后端端点	用途
stocktrends_estimate_workflow_cost	GET /v1/cost-estimate	在付费执行前估算工作流级别的成本，用于预算/规划。

此工具不会发送 API 密钥或身份验证标头，不会调用付费端点或 /v1/pricing/catalog，不会授权付费执行或付款，也不会实现 x402 付款、钱包、OAuth、数据库或控制平面行为。 另外两个免费的工具发现工具也已在本地默认/免费模式下注册：

MCP 工具	后端端点	用途
stocktrends_lookup_instruments	GET /v1/instruments/lookup	无需付款或 API 密钥即可查找匹配的 Stock Trends 工具标的。
stocktrends_resolve_instrument	GET /v1/instruments/resolve	无需付款或 API 密钥即可解析 Stock Trends 工具标的标识符。

已部署的 Remote MCP 提供相同的三个免费工具；请参阅公共 Remote MCP。

有条件开放的付费 ST-IM 工具（订阅/API 密钥执行）

当配置了 STOCKTRENDS_ENABLE_PAID_TOOLS=true 和 STOCKTRENDS_API_KEY 时，服务还会注册成对的付费 ST-IM 工具定义、成对的付费指标工具定义、基础选项工具定义以及四个市场上下文工具定义（三个免费工具加九个付费工具，共 12 个；参见付费模式配置）。否则只注册三个免费工具。工具是否开放与执行标志相互独立。

MCP 工具	端点	执行方式
stocktrends_get_stim_latest	GET /v1/stim/latest	仅当所有关卡均通过时才进行实时订阅/API 密钥调用；否则会安全拒绝。
stocktrends_get_stim_history	GET /v1/stim/history	仅当所有关卡均通过时才进行实时订阅/API 密钥调用；否则会安全拒绝。

这两个工具始终成对注册（历史记录与最新数据配对规则）。每次调用都会严格验证输入（符号身份优先采用 symbol_exchange，交易所须为 N,Q,A,B,T,I 之一，历史记录日期和 limit 的范围为 1–2600），并且验证发生在任何预检、身份验证或获取操作之前。只有在 STOCKTRENDS_ENABLE_PAID_EXECUTION=true、已配置 API 密钥、权威静态定价/预检解析成功、静态定价镜像与实时 /v1/pricing/catalog 元数据核对一致（此操作是无需凭据的读取；仅凭静态定价不能授权调用，若不匹配/不可用则会安全拒绝），且非零本地上限（以及涵盖非零成本的预算上限）均通过时，才会进行实时调用——随后仅发送一个带有 X-API-Key 的 GET 请求（不使用 Authorization: Bearer、不使用付款标头、不自动重试、不使用 x402）。携带凭据的边界仅限九个获准的付费端点（/v1/stim/latest、/v1/stim/history、/v1/indicators/latest、/v1/indicators/history、/v1/selections/latest、/v1/market/regime/latest、/v1/market/regime/history、/v1/breadth/sector/latest、/v1/leadership/summary/latest）；公共工具发现路由（/v1/instruments/lookup、/v1/instruments/resolve）、无需凭据的 /v1/leadership/definitions 资源路由、延期开放的选项路由（/v1/selections/history、/v1/selections/published/*）、延期开放的市场上下文路由（/v1/market/regime/forecast、/v1/breadth/sector/history、/v1/leadership/rotation/history）以及任何其他尚未开放的端点，都绝不会收到 X-API-Key。符号身份会以连字符形式（SYMBOL-EXCHANGE）发送给 API；绝不会转发下划线规范形式。成功响应会包装在透明的 MCP 元数据中（paid_execution_authorized: true、api_request_sent: true、auth_header_sent: true、payment_header_sent: false、observed_cost: null、payment_status: null），并在 api_data 中原样保留 API 负载。任何关卡未通过都会返回确定性且不含秘密信息的拒绝结果，其中 paid_execution_authorized: false，并且不会发送请求/身份验证/付款标头。自动化验证仅使用模拟对象；测试中不会运行实时 API 调用。参见 Phase 4 Paid ST-IM Live Execution (Subscription) Implementation Notes 和 docs/SECURITY_MODEL.md §15。

条件式付费指标工具（通过订阅/API 密钥执行）

启用付费工具并提供 API 密钥后，服务器还会在 ST-IM 工具对旁注册配套的付费指标工具定义（计入付费模式配置中所述的十二工具付费开放范围）。它们始终成对注册（历史数据与最新数据并列规则），行为与 ST-IM 工具对完全相同，另有一点：在任何付费边界之前，都会运行一个内部、无需凭据的工具解析器。

MCP 工具	端点	执行方式
stocktrends_get_indicators_latest	GET /v1/indicators/latest	仅当安全的规范身份解析成功且所有门控条件均通过时，才会进行实时订阅/API 密钥调用；否则将拒绝执行。
stocktrends_get_indicators_history	GET /v1/indicators/history	仅当安全的规范身份解析成功且所有门控条件均通过时，才会进行实时订阅/API 密钥调用；否则将拒绝执行。

输入可接受规范的 symbol_exchange（下划线格式，例如 IBM_N）、显式的 symbol + exchange（exchange 为 N,Q,A,B,T,I 之一），或不带其他字段的原始 symbol，还可选 cs_only；历史数据工具还可选 start/end 和 limit（1–2600，省略时 API 默认值为 260）。身份会在任何付费边界之前，无需凭据地解析：

• 规范的 symbol_exchange 会直接采用（不调用发现接口），并以连字符格式（IBM-N）发送给 API。
• 显式的 symbol + exchange 会通过 GET /v1/instruments/resolve 验证，并显式将 prefer_exchange 设为提供的 exchange——绝不使用默认值 N。
• 不带其他字段的原始 symbol 会通过 GET /v1/instruments/lookup 消除歧义：恰好有一个匹配项时，无需凭据即可解析；多个匹配项时将拒绝执行，并返回候选 symbol_exchange 匹配项，且不会进行付费调用。解析器有意不依赖 /v1/instruments/resolve 对原始代码默认使用的 prefer_exchange=N，因此服务器绝不会擅自为你选择交易所。

只有在确定唯一且安全的规范身份后，工具才会执行与 ST-IM 相同的付费门控：权威静态定价（特定类别镜像：indicators_latest_paid 为 0.0035 STC，indicators_history_paid 为 0.01 STC）、对照实时 /v1/pricing/catalog 元数据验证该镜像（无需凭据；仅有静态定价绝不构成调用授权；不匹配或元数据不可用时将拒绝执行）、本地上限非零，以及执行标志。随后只发送一个 GET 请求，且仅使用 X-API-Key（不使用 Authorization: Bearer，不发送支付标头，不自动重试，也不使用 x402）。工具发现和目录读取请求绝不会收到 API 密钥。这个付费指标解析器是一个内部辅助程序，不同于两个公开发现工具，因此默认/免费功能仍只有三个工具。成功响应会在 api_data 中原样保留 API 载荷，并添加包含 instrument_resolution 的 mcp_metadata（存在歧义时还会包含 candidate_matches）；observed_cost/payment_status 始终为 null，绝不会伪造。自动化验证仅使用模拟数据；测试中不会运行实时 API 调用。请参阅第 5B 阶段指标实现说明。

条件性付费选股工具（订阅/API 密钥执行）

启用付费工具并提供 API 密钥时，服务器还会注册一个基础 ST-IM 选股范围工具，与 ST-IM 和指标工具对一同提供（计入付费模式配置中所述的十二工具付费暴露面）。它遵循与其他付费工具相同的门控策略，并额外采用列表型宽范围扫描/限额安全控制，因为它返回的是选股范围/列表，而非单行数据。它按交易所限定，而非按代码索引，因此不使用证券解析器。

MCP 工具	端点	执行方式
stocktrends_get_selections_latest	GET /v1/selections/latest	仅当所有门控条件通过且限额有界时，才发起实时订阅/API 密钥调用；否则安全失败。

此工具展示基础 ST-IM 选股范围（API 按 prob13wk 排名）。它不是严格的已发布 STIM Select 列表——后者是单独的端点（/v1/selections/published/latest），会应用已发布阈值。此工具绝不会将基础行呈现为已发布列表，不会在本地应用已发布阈值，也不会在本地对行进行排名、设阈值、评分、筛选或以其他方式重新计算；mcp_metadata 会携带基础范围来源信息，避免混淆这两种数据。本次增量不会添加 selections/history、selections/published/* 或公共选股资源。

输入（全部可选，严格架构，拒绝未知键）：exchange（取值之一：N,Q,A,B,T,I）、min_prob13wk（0–1）、limit（整数 1–250，默认值为 50）、include_data（默认值为 false）、include_mast（默认值为 false）以及 cs_only（默认值为 true）。min_prob13wk、exchange、cs_only 和 include_* 标志只会传递给 API，不会在本地应用。

宽范围扫描/限额安全（远严于 API 自身的 2000 默认值 / 20000 上限）：

• 始终发送显式 limit（默认值为 50）；绝不会采用 API 的 2000 默认值。硬上限为 250；若 limit 大于 250、小于 1、不是整数、是数组或为任何哨兵值，则会在任何计价/认证/获取操作之前安全失败——绝不静默截断。没有获取全部行/扫描整个选股范围的模式。
• 每次调用恰好一个 GET——不分页、不遍历偏移量、不自动遍历多个交易所、不批量组装、不后台刷新，也不会在 429/5xx 时自动重试（安全失败）。
• 调用上限默认拒绝，且必须有覆盖 0.05 STC 费用的 STOCKTRENDS_MAX_STC_PER_SESSION。同一会话内重复发起完全相同的基础选股调用时会安全失败（repeated_identical_selection_call），而不会静默重复收费。

计价使用全新的 selections 系列静态镜像（selections_latest_paid，0.05 STC），并以无凭据且限定系列的方式，与实时 /v1/pricing/catalog 元数据核对（缺失/重复规则、费用不匹配，或 STC 单位缺失/不受支持/冲突时均安全失败；ST-IM/指标/已发布镜像均不能替代）。所有门控条件通过后，仅发送一个带 X-API-Key 的 GET（不使用 Authorization: Bearer、不添加支付标头、不使用 x402、不重试）。成功响应会在 api_data 中原样保留 API 负载，并添加包含基础与已发布数据来源信息、effective_limit 和返回行数的 mcp_metadata；observed_cost/payment_status 保持为 null，绝不伪造。自动化验证仅使用模拟；测试中不会运行实时 API 调用。请参阅阶段 5C 选股/最新实现说明。

条件性付费市场情境工具（订阅/API 密钥执行）

使用 API 密钥启用付费工具后，服务还会注册 4 个 Phase 5D 市场背景工具，与此前的工具系列并列，使本地订阅/API 密钥付费开放的工具总数达到 12 个（3 个免费工具加 9 个付费工具）。它们遵循与其他付费工具相同的访问门控策略，并针对数据按周更新且按市场划分的特点，增加了市场背景限制安全控制。这些工具都不以证券代码为键，因此无需调用证券解析器。

MCP 工具	端点	费用	限制（始终发送）
stocktrends_get_market_regime_latest	GET /v1/market/regime/latest	0.15 STC	—（快照；输入必须严格为空，拒绝未知键）
stocktrends_get_market_regime_history	GET /v1/market/regime/history	0.25 STC	limit 默认值为 12，硬上限为 52（API 自身的上限）；可选的 start_date（YYYY-MM-DD）原样传递
stocktrends_get_breadth_sector_latest	GET /v1/breadth/sector/latest	0.1 STC	limit 默认值为 50，硬上限为 250；始终发送默认值为 sector 的 group_level
stocktrends_get_leadership_summary_latest	GET /v1/leadership/summary/latest	0.25 STC	limit_overall 默认值为 50，硬上限为 200；limit_bucket 默认值为 20，硬上限为 50

提供背景信息，而非建议。 这些工具会逐字转发由 Stock Trends API 撰写的市场背景信息，绝不会将其转化为建议：制度标签是市场背景信息，而非交易建议；广度行是参与度背景信息，而非可据以行动的确认信号；领军者表是轮动背景信息，而非精选标的。适配器不会在本地计算市场制度、重新汇总市场广度，或重新排列/重新分组/设定阈值来处理领军者，也不会输出买入/卖出/持有/配置或适当性结论。

其他输入策略：exchange（取值为 N,Q,A,B,T,I 之一）、市场广度的 cs_only/include_unknown/min_price/min_volume，以及领军者的 min_rsi/min_mt_cnt（0–500）均会经过校验，并且仅在提供时才原样传递，以便使用 API 默认值；这些参数都不会在本地应用。两个最新数据工具都刻意不开放 weekdate（不会通过最新数据路由进行快照时间穿越来重建历史）；vol_scale（无界的旧版乘数）和 type（未验证的枚举）也不开放；这些参数均会被作为未知键拒绝。无效/越界/数组/哨兵限制会在任何计价、身份验证或获取操作之前导致请求失败，且绝不会被钳制。每次调用恰好执行一次 GET——不分页、不扫描日期范围、不遍历交易所、不批量组装，也不自动重试——相同调用（同一工具 + 规范化参数；无参数的市场制度最新数据工具签名恒定）若重复执行，会以 repeated_identical_market_context_call 为由拒绝，避免对每周更新的数据重复收费。 定价涉及 3 个全新的、按系列划分的静态镜像（系列 market 中的 market_regime_latest 0.15 STC 和 market_regime_history 0.25 STC——已验证的规则 ID 不带 _paid 后缀；系列 breadth 中的 breadth_sector_latest_paid 0.1 STC；系列 leadership 中的 leadership_summary_latest_paid 0.25 STC）。每个镜像都会对照实时 /v1/pricing/catalog 元数据进行无需凭据的核验，并执行相同的失败关闭检查（规则缺失或重复、端点／系列／费用／单位不匹配、分类并非 paid）。延后实现的路由 /v1/market/regime/forecast、/v1/breadth/sector/history（API 默认值／上限为 200000／500000——此适配器绝不会访问该路由）和 /v1/leadership/rotation/history 均未实现、未开放，并会被拒绝，错误为 endpoint_not_allowlisted。成功响应会在 api_data 中原样保留 API 负载，并添加 mcp_metadata，其中包含“仅供参考，不构成建议”的来源说明、effective_limits、可推导时返回的行数，以及仅在 API 报告周日期时才包含的周日期；observed_cost／payment_status 始终为 null，绝不会伪造。自动化验证仅使用模拟数据；测试不会发起实时 API 调用。请参阅第 5D 阶段市场背景实现说明和docs/SECURITY_MODEL.md §17。

文档

• 架构决策
• MCP 服务架构
• API 能力覆盖审计
• 安全模型
• 第 1 阶段实现备忘录
• 第 1 阶段验证报告
• 第 1 阶段实现说明
• 第 2 阶段公开元数据和付费工具边界备忘录
• 第 2 阶段公开元数据实现说明
• 第 3 阶段付费工具身份验证和支出设计备忘录
• 第 3 阶段付费身份验证基础实现说明
• 第 4 阶段首个付费工具契约备忘录
• 第 4 阶段 API 契约确认备忘录
• 第 4 阶段定价/预检基础实现说明
• 第 4 阶段定价/预检基础验证报告
• 第 4 阶段成本估算 MCP 集成备忘录
• 第 4 阶段成本估算规划工具实现说明
• 第 4 阶段成本估算规划工具验证报告
• 第 4 阶段首个付费 ST-IM 工具预检设计备忘录
• 第 4 阶段付费 ST-IM 基础（不执行）实现说明
• 第 4 阶段付费 ST-IM 基础（不执行）验证报告
• 第 4 阶段付费 ST-IM 实时执行设计备忘录
• 第 4 阶段付费 ST-IM 实时执行（订阅）实现说明
• 第 4 阶段付费 ST-IM 实时执行（订阅）验证报告
• 第 5A 阶段 MCP Inspector 验证操作手册
• 第 5A 阶段运维人员安全与发布清单
• 第 5B 阶段指标和工具解析设计备忘录
• 第 5B 阶段指标契约验证备忘录
• 第 5B 阶段指标实现说明
• 第 5B 阶段指标受控验证计划
• 第 5B 阶段指标生产就绪签核
• 第 5C 阶段下一项能力选择备忘录
• 第 5C 阶段选择项/最新版本设计和契约验证备忘录
• 第 5C 阶段选择项/最新版本实现说明
• 第 5C 阶段选择项/最新版本受控验证计划
• 第 5C 阶段选择项/最新版本受控验证报告
• 第 5C 阶段选择项/最新版本生产就绪签核
• 第 5D 阶段 MCP 启动能力路线图和可用端点选择备忘录
• 第 5D 阶段市场上下文层设计和契约验证备忘录
• 第 5D 阶段市场上下文实现说明
• 第 5D 阶段市场上下文受控验证计划
• 第 5D 阶段市场上下文受控验证报告
• 第 5D 阶段市场上下文生产就绪签核
• 第 5E 阶段下一项能力选择备忘录
• 第 5E 阶段启动/分发就绪设计备忘录
• 第 5E 阶段运维人员冒烟测试操作手册
• 第 5E 阶段启动发布清单
• 第 5E 阶段目录/市场元数据就绪情况
• 第 5E 阶段受控本地客户端验证报告
• 第 5E 阶段本地 Stdio 启动就绪签核
• 第 5F 阶段 x402 中继架构备忘录
• 第 5F 阶段 x402 契约验证计划
• 第 5F 阶段 x402 契约验证报告
• 第 5F 阶段 x402 中继实现设计备忘录
• 第 5F 阶段 x402 挑战中继模拟实现说明
• 第 5F 阶段 x402 模拟验证报告
• 第 5F 阶段 x402 公开挑战中继接线设计备忘录
• 第 5F 阶段 x402 公开模拟接线实现说明
• 第 5F 阶段 x402 公开模拟接线验证报告
• 第 5F 阶段 x402 实时无密钥挑战中继计划
• 第 5F 阶段 x402 实时无密钥挑战实现说明
• 第 5F 阶段 x402 实时无密钥挑战中继验证报告
• 第 5F 阶段 x402 实时挑战契约偏差诊断
• 第 5F 阶段 x402 API 挑战契约确认
• 第 5F 阶段 x402 v2 验证器协调实现说明
• 第 5F 阶段 x402 实时挑战重新验证报告
• 第 5F 阶段 x402 价值策略不匹配调查
• 第 5F 阶段 x402 最终响应封装协调实现说明
• 第 5F 阶段 x402 最终响应封装实时重新验证报告
• 第 5F 阶段 x402 收尾和路线图交接备忘录
• 软件包制品和安装验证架构
• 软件包运行时依赖契约修正
• 软件包身份和许可证决策记录
• 软件包元数据和封闭式制品允许列表实现
• 离线软件包和制品内容验证报告
• B-5 POSIX 已安装 Bin 修正备忘录
• 跨平台软件包安装/Stdio 验证报告
• 软件包文档刷新和尾部验证报告
• 软件包就绪收尾和发布决策交接
• 软件包发布和分发决策架构
• 软件包发布平台就绪情况验证
• 软件包发布账户和名称就绪情况报告
• 软件包发布组织就绪收尾
• 软件包发布实现决策
• 软件包发布配置实现说明