stock_mcp

stock_mcp 是一个面向股票基础数据、板块资金流和 CN_A 大盘晨报事实证据的 MCP Server、Python 库和 JSON CLI。它把股票代码解析、交易日处理、多源行情回退、市场级快照、板块/成分股资金流排名、字段标准化、质量评估、运行时保护和可追溯诊断放在同一条可测试的数据链中。

当前生产闭环面向 CN_A。项目提供港股数据模型、字段契约、fixture 和 Futu adapter 接口，但默认生产入口不提供港股真实查询。大盘晨报 v1 只输出事实证据，不提供总评分、恐慌/贪婪合成、投资建议、买卖信号、仓位、目标价或报告型结论。

适用范围

能力	当前状态	说明
MCP Agent 接入	支持	默认 stdio；可显式启动仅绑定本机的 Streamable HTTP。
CN_A 生产查询	支持	生产入口会按 source TTL 自动构建或刷新本地身份索引和交易日历；部署或批量查询前建议预热。
CN_A 实时行情	支持	默认回退顺序为东财、腾讯、新浪。
CN_A provider-defined 五档盘口	支持显式查询	独立 Tencent order_book chain，仅支持 SH/SZ；BJ 在 HTTP 前跳过。数量保持 provider 原始单位，不声称完整 L2、逐笔、full-book、队列位置或可成交保证。
CN_A 板块资金流	支持	支持行业/概念；默认只返回流入、流出前 10 个板块，--level 1 每板块附前 3 股，--level 2 附前 10 股，--all 返回全部板块。
CN_A 大盘晨报证据	支持	当前晨报窗口内查询七个封闭组件；成功结果始终为 partial，逐组件表达质量、来源、时间和缺失原因，不生成评分或交易动作。
CN_A 可选资料	支持	显式传入 --include-profile 或 include_profile=True；默认原子降级为东财轻量资料→CompanySurvey 公司资料，资料失败不影响行情成功结果。
CN_A 可选分析证据	支持	显式传入 --include-analysis 或 include_analysis=True；个股前复权日线按东财→腾讯降级，代理指数未复权日线按东财→腾讯→新浪降级，并可读取独立维护的收盘市场环境与板块强度历史；附加证据失败不影响行情成功结果。
业务评分	仅 CN_A	默认开启五项轻量 stock_score，可用 --no-score 关闭；同时启用 analysis 时另返回严格 33 子项 detailed_scorecard。v6 共实现 24 项机械评分，包括四项板块、十二项本地技术规则及三项用户计划相关规则；缺精确证据的子项为 null，模板总分和评级在不完整时保持 null。港股不会调用评分器。
用户交易计划与持仓复盘输入	支持封闭输入	Python、CLI 和 MCP 可传兼容的 schema_version=1.0 long plan，或 schema_version=1.1 的用户持仓复盘 facts；v1.1 输出 user_trade_plan_assessment_v4 的 V4 脱敏 presence/state，不回显 rationale、日期、关键位、百分比、账户/持仓/订单原值，也不生成卖出评分、交易动作或建议。
浏览器候选源	受控测试能力	ths_quote 默认禁用，不进入生产默认链。
HK fixture	测试能力	仅用于市场隔离和注入式集成测试，不是真实行情。
HK Futu source	注入式/live 能力	默认禁用，CLI 不会静默回退到 fixture。
语义映射	支持	可将语义文档、配置、枚举和 SQLite schema 投影到 support SQLite。

单股结果现在额外提供封闭 phase_timings_ms，分别记录 support、calendar、quote、profile、analysis 墙钟耗时；未执行的可选阶段为 null。production 边界的成功和早退结果还包含 total_duration_ms 与 boundary_timings_ms，CLI 进程启动/import 明确排除。source attempt 的 physical_requests 按每次物理请求/guard 记录 transport、限流、并发、退避和最终成功 evaluator 耗时；所有文本保持脱敏。analysis source attempts 带 component/target_role，末端校验失败可带只含封闭阶段/原因码的 analysis_failure；validator 自身的非合同异常使用 VALIDATOR_INTERNAL_ERROR，不公开异常文本或字段值。合法 partial analysis 即使缺 profile、行业、板块、市场环境或公告等可选证据，也保留固定 33 行 detailed_scorecard，缺失项继续为 null。这些字段用于诊断，不改变顶层 quote 质量、fallback 顺序或评分口径。

当前生成的个股、基准和行业技术指标还包含封闭 input_windows，逐项给出登记窗口、实际连续可用会话数，以及 available、insufficient_history、source_fields_unavailable 或 derivation_unavailable。它只解释 MA、收益、结构、ATR、KDJ、枢轴和个股量价事实的输入资格，不参与评分或质量计算。Tencent stock qfq 已核实并原子映射 qfqday 成交量（lot→万股），因此仅依赖 volume 的窗口可按实际数据变为 available；Tencent amount/pct-change、Tencent index volume 和 Sina volume/amount 仍不映射，也不跨 source 补齐。

CN_A Runtime 对不超过 0.5 秒的 min_interval 最多等待一次，并且等待必须短于剩余 HTTP deadline、发生在并发 lease 外；不会因此增加 retry。Sina 行情从原始 bytes 验证中文编码，Tencent 接受严格单键 wrapper 的 tilde 字符串。公告列表可剔除其他身份/日期字段合法但完全缺目标证券的少量坏行并标记 partial；错误证券身份、日期或公告编号仍整组件失败。

stock_profile.cn_a.default 使用 first_complete_then_best_partial：eastmoney_profile_lite 完整时立即短路；其失败时才请求 eastmoney_company_profile。CompanySurvey fallback 可独立证明公司名称、经营范围、EM2016 行业和上市日期，并可让现有 current-only 行业链继续执行，但它不提供总股本/流通股本，因此结果保持 partial。两套 profile 不跨 source 拼字段，不使用更宽泛的 INDUSTRYCSRC1 冒充当前行业目录分类，也不把当前成员资格描述为历史 point-in-time 事实。

快速开始

以下命令在仓库根目录执行。

1. 安装

要求 Python 3.11 或更高版本。

python3 -m venv .venv
.venv/bin/python -m pip install -e '.[test]'

下面的 CLI 示例统一使用模块入口，因此不依赖 PATH 或 console script 是否已生成。完成 editable 安装后，stock-mcp 等价于 .venv/bin/python -m stock_mcp.cli，stock-mcp-server 等价于 .venv/bin/python -m stock_mcp.mcp_server。

默认生产查询（包括 --include-profile）不依赖或隐式调用 AKShare。只有身份索引管理命令显式使用 --provider akshare 时才需要安装可选兼容依赖；doctor --include-profile 也会检查该依赖，未安装时将 akshare_profile 报告为 missing：

.venv/bin/python -m pip install -e '.[profile]'

2. 预热 CN_A 支撑缓存