Skip to content

ccchenhuohuo/flywheel-mcp

BranchesTags

Repository files navigation

Flywheel MCP

CI

面向公司内部市场分析的受治理数据服务。Flywheel MCP 把自然语言问题转换为可解释、可校验、可回放的 Doris 查询和固定分析场景，让同事无需了解表结构或编写 SQL，也能稳定查询市场规模、趋势、结构、类目变化、增长驱动、受治理价格带、品牌份额/集中度/结构变化和单 SKU 月度表现。

它不是“让模型直连数据库”，而是由两层能力共同完成一次可靠回答：

  • MCP 服务负责指标口径、数据水位、查询安全、币种换算和确定性计算；
  • Strategic Analytics Skill负责理解问题、选择场景、处理澄清、组织证据和约束回答边界。

当前交付基线为 MCP/语义层 0.7.0、固定分析场景 1.6.0。11 个公开指标均为 active，负责人为 陈煜-战略分析师（Fika chen）。

组件 当前基线
MCP 服务 / npm 包 0.7.0
语义层 0.7.0
指标定义 0.5.0，11 个 active 指标
固定分析场景 1.6.0，11 个场景
币种映射源 1.1.0，状态 active
价格带政策 1.0.0，CNY / USD / EUR / JPY 各 8 档
标准类目映射 1.0.0，111 条 L1→L2→L3 发布路径
运行环境 Node.js 20+、TypeScript、Streamable HTTP / stdio

文档入口

你想了解什么 文档
真实业务问题、实际数据快照与最终回答 真实使用案例与回答
版本变化和发布状态 CHANGELOG
MCP 与 Skill 为什么必须搭配、如何安装和联动 MCP × Skill 联动指南
全部功能、工具和使用流程 功能与使用场景
11 个固定分析场景的输入、算法和边界 业务分析场景
QueryIntent、时间解析、实体标准化与澄清 自然语言意图层
系统分层和关键技术决策 架构设计
指标、维度、范围和明细实体契约 语义层设计
公司标准类目父子关系和受控下钻 标准类目映射与下钻
指标负责人和首发治理结论 指标与币种治理
真实 Doris 数据画像与质量风险 Doris 数据画像
共享部署前需要完成的检查 生产上线清单
Codex 在本仓库中的开发规则 AGENTS.md
Claude Code 在本仓库中的开发规则 CLAUDE.md

项目解决什么问题

传统的自然语言查数容易在三个地方出错：模型误解业务词、模型临时发明计算方式、模型直接生成不可控 SQL。本项目把这三类风险拆开治理：

  1. MCP Host 理解用户想问什么，但不决定指标公式或 SQL；
  2. Skill 把问题路由到标准 QueryIntent 或固定分析场景；
  3. 语义层把业务名称解析成稳定逻辑 ID，并验证真实维度值；
  4. 查询内核执行白名单、月份边界、币种、范围和返回规模检查；
  5. 固定场景用十进制定点算子计算增长、份额、贡献和排名；
  6. Skill 根据结构化结果生成有边界的业务回答，不补写因果或战略建议。
flowchart LR
  U["同事的自然语言问题"] --> H["Codex / Claude Code / MCP Host"]
  H --> K["Strategic Analytics Skill"]
  K --> M["Flywheel MCP"]
  M --> I["意图、实体与时间标准化"]
  I --> S["版本化语义层与固定场景"]
  S --> Q["安全查询编译器"]
  Q --> D["Doris"]
  S --> F["ECB 最新参考汇率"]
  D --> C["确定性计算与质量门禁"]
  F --> C
  C --> K
  K --> A["带口径、范围和警告的回答"]
Loading

MCP 与 Skill 的职责边界

能力 MCP 服务 Strategic Analytics Skill
指标、维度和版本 唯一权威来源 运行时发现并遵守
自然语言理解 不调用模型 识别意图并选择标准路径
SQL 只生成白名单 prepared statement 永不生成或修改 SQL
时间 根据数据水位确定性解析 识别“最近完整月、同比、环比”等表达
币种 强制本币/CNY 聚合安全并执行换算 识别用户币种偏好，必要时澄清
业务计算 计算增长、份额、排名、数学贡献和受治理价格带 不重复计算固定场景结果
SKU 搜索候选、签发 skuRef、执行粒度守卫和源观测投影 展示候选、要求选择并正确解释观测值
最终回答 返回结构化结果、警告和方法 组织结论，不推断因果或给深度战略建议

详细的调用时序、安装方式和错误处理见 MCP × Skill 联动指南。

当前数据与分析能力

受治理范围

当前 scopeVersion=1.0.0，数据用于描述：

公司关注的重点电商平台与重点 3C 类目范围内的市场表现。

当前纳入 Amazon、Taobao、Tmall 3 个平台，以及 US、DE、JP、cn 4 个站点。该口径适合内部关注市场分析，但不扩张为所有平台、所有类目的完整市场。

数据按完整月交付：上一业务月以次月 16 日为交付边界；表中新的最大月份一经出现即视为完整月份。运行时结果会返回最新完整月、预期完整月、范围版本和水位状态。

指标与维度

  • 11 个指标：估算销量；折后/页面价估算销售额、加权折后/页面价、折后金额比例的站点本币版本；以及对应的 5 个 CNY 报告指标。
  • 15 个目录维度：平台、站点、设备类型和标准一/二/三级类目是默认分析口径；8 个平台原始类目维度仅在用户明确要求时使用，必须限定单一 platform + site 并以完整路径识别成员；Flywheel 标准品牌标签属于高基数维度，具名过滤先搜索，普通分组/排名保持单月 limit≤20，完整份额、集中度、覆盖与两期变化使用品牌专用固定场景。
  • 场景专用价格带：不是第 12 个指标或通用物理维度。默认按 discount_price，可明确切换 page_price；auto 在单站点默认使用本币档位，用户也可显式选择 CNY，跨站点则必须先按同一快照换算为 CNY，再按两位小数和左闭右开边界划带。
  • 标准类目树：1.0.0 发布快照固化 111 条标准 L1→L2→L3 路径；父类目下钻先枚举完整子节点，再以 parentFilters + childDimension 执行现有场景，并把映射版本/快照哈希作为前置条件原样传入。选定一个返回子节点后，也可用其完整过滤器继续按站点、平台或设备分析，无需再次搜索类目值。服务区分全体子节点和选定成员两种对账，未观察保持不可用，映射外事实失败关闭。
  • 单 SKU 明细：必须先搜索并选择一个 platform + site + productId + skuId 四元身份，再使用服务签名的 skuRef 执行固定场景。除 6 个聚合指标外，月度快照还返回该来源行的折后/页面价、原始/标准品牌、平台原始类目上下文、上架月份和估算生命周期区间；这些是 SKU 专用观测值，不是新的通用指标或维度。

跨站点金额在未明确要求本币时默认换算为 CNY；明确要求“本币”时按站点分别展示，不产生跨站点合计。CNY 使用请求时的 ECB latest daily reference，不用于交易结算或财务对账。

固定业务场景

场景 典型问题 主要输出
market_trend 最近一年市场规模怎么变化？ 月度值、环比、同比、峰谷和连续趋势
market_structure 各平台或站点占多少？ 份额、排名、累计份额和 Top N 覆盖
category_growth 哪些类目增长、下滑或份额变化？ 增长率、份额变化、排名和数学贡献
growth_driver 本月下降主要由哪些站点构成？ 正负向绝对变化和数学贡献分解
price_discount_change 单站点价格和折后率怎么变化？ 销量、金额、加权价格和比例变化
market_structure_change 市场结构相对上期怎么变化？ 份额、排名和集中度变化
dimension_coverage_quality 三级类目的覆盖情况如何？ 指标值加权覆盖率和变化
sku_performance 某个 SKU 最近几个月表现如何？ 月度指标、直接价格、品牌、类目和估算生命周期
price_band_structure 5 月各价格带的量额结构如何？ 各档销量、销售额、双份额、双排名和价格覆盖率
brand_structure 品牌份额、CR5 和覆盖怎么样？ 份额、排名、CR1/3/5/10、覆盖率和 HHI 区间
brand_growth_driver 哪些品牌构成了本月增长或下降？ 品牌变化、增长率和正负向数学贡献分解

Monthly Market Review 不是额外的自由场景，而是由 Skill 按固定配方组合趋势、结构、类目和驱动结果。这样既能形成完整月度回顾，也不会引入另一套计算口径。

MCP 工具

服务公开 13 个只读工具：

分类 工具
目录发现 flywheel_list_metrics、flywheel_describe_metric、flywheel_list_dimensions
标准类目导航 flywheel_list_standard_category_children
实体搜索 flywheel_search_dimension_values、flywheel_search_skus
自然语言分析 flywheel_validate_analysis、flywheel_run_analysis
固定场景发现 flywheel_list_analyses、flywheel_describe_analysis
精确机器查询 flywheel_validate_query、flywheel_query_metrics
数据状态 flywheel_get_data_status

服务不提供 execute_sql，也不会向普通调用方暴露物理表名或完整 SQL。

其中 flywheel_describe_analysis(price_band_structure) 会直接投影当前 active 价格带政策的版本/哈希和完整币种 profiles；只查询价格带定义时不需要执行 Doris 查询，也不应在 Host 或 Skill 中维护第二份边界表。

安装 MCP 与 Strategic Analytics Skill

MCP 是数据与计算内核，Skill 是 Host 侧的路由与解释协议；两者必须来自同一个 release/tag。只安装其中一个都不是完整交付。

1. 准备服务

要求 Node.js 20 或更高版本。从仓库根目录执行：

git clone https://github.com/ccchenhuohuo/flywheel-mcp.git
cd flywheel-mcp
git checkout v0.7.0
corepack enable
pnpm install --frozen-lockfile
cp .env.example .env
pnpm check
pnpm build
export FLYWHEEL_MCP_HOME="$(pwd)"

编辑本地 .env，至少填写 DORIS_HOST、DORIS_PORT、DORIS_USER 和 DORIS_PASSWORD。数据集已在受治理语义层中声明数据库；DORIS_DATABASE 仅在数据集未声明数据库时作为可选 fallback。不要把 .env 或真实凭据提交到 Git。下面配置中的 /absolute/path/to/flywheel-mcp 均替换为 FLYWHEEL_MCP_HOME 显示的绝对路径。

2. Codex（CLI / IDE 扩展）

安装用户级 Skill：

mkdir -p "$HOME/.agents/skills"
cp -R "$FLYWHEEL_MCP_HOME/skills/strategic-analytics" "$HOME/.agents/skills/"

在 ~/.codex/config.toml 中增加：

[mcp_servers.flywheel]
command = "node"
args = ["/absolute/path/to/flywheel-mcp/dist/stdio.js"]
cwd = "/absolute/path/to/flywheel-mcp"
required = true
startup_timeout_sec = 20
tool_timeout_sec = 120

[mcp_servers.flywheel.env]
SEMANTIC_LAYER_PATH = "/absolute/path/to/flywheel-mcp/config/semantic-layer.yaml"
STANDARD_CATEGORY_MAPPING_PATH = "/absolute/path/to/flywheel-mcp/config/standard-category-mapping.yaml"
CURRENCY_MAPPING_PATH = "/absolute/path/to/flywheel-mcp/config/currency-mapping.yaml"
PRICE_BAND_POLICY_PATH = "/absolute/path/to/flywheel-mcp/config/price-band-policy.yaml"

重启 Codex，用 codex mcp list 或 /mcp 确认 flywheel 已连接，再以 $strategic-analytics 显式调用（匹配请求也可自动触发）。Codex CLI 和 IDE 扩展使用这份 config.toml。

3. Claude Code（CLI / Desktop Code 页签）

安装用户级 Skill：

mkdir -p "$HOME/.claude/skills"
cp -R "$FLYWHEEL_MCP_HOME/skills/strategic-analytics" "$HOME/.claude/skills/"

添加本地 stdio MCP（将路径替换为实际值）：

claude mcp add --scope user flywheel \
  --env SEMANTIC_LAYER_PATH=/absolute/path/to/flywheel-mcp/config/semantic-layer.yaml \
  --env STANDARD_CATEGORY_MAPPING_PATH=/absolute/path/to/flywheel-mcp/config/standard-category-mapping.yaml \
  --env CURRENCY_MAPPING_PATH=/absolute/path/to/flywheel-mcp/config/currency-mapping.yaml \
  --env PRICE_BAND_POLICY_PATH=/absolute/path/to/flywheel-mcp/config/price-band-policy.yaml \
  -- /bin/sh -c \
  'cd "/absolute/path/to/flywheel-mcp" && exec node dist/stdio.js'
claude mcp get flywheel

重新加载 Claude Code，用 /mcp 检查工具，以 /strategic-analytics 显式调用。如果只需当前项目使用，也可把 Skill 复制到项目根目录的 .claude/skills/strategic-analytics。

4. Claude Desktop Chat 页签

Claude Desktop 的 Chat 页签与 Claude Code/Desktop Code 页签不共享 MCP 配置。本仓库尚未提供官方当前推荐的 .mcpb Desktop Extension，因此没有一键式 MCP 安装。macOS 版若仍提供 Settings → Developer → Edit Config，可把下面的直接 stdio 配置用于单机开发；如果客户端或组织策略只允许 Settings → Extensions 安装 .mcpb，当前 release 的 Desktop Chat MCP 暂不可用，应使用 Claude Code，不能把 Skill 单独上传后误认为已经接通数据。

打开 ~/Library/Application Support/Claude/claude_desktop_config.json，增加：

{
  "mcpServers": {
    "flywheel": {
      "command": "/bin/sh",
      "args": ["-c", "cd \"/absolute/path/to/flywheel-mcp\" && exec node dist/stdio.js"],
      "env": {
        "SEMANTIC_LAYER_PATH": "/absolute/path/to/flywheel-mcp/config/semantic-layer.yaml",
        "STANDARD_CATEGORY_MAPPING_PATH": "/absolute/path/to/flywheel-mcp/config/standard-category-mapping.yaml",
        "CURRENCY_MAPPING_PATH": "/absolute/path/to/flywheel-mcp/config/currency-mapping.yaml",
        "PRICE_BAND_POLICY_PATH": "/absolute/path/to/flywheel-mcp/config/price-band-policy.yaml"
      }
    }
  }
}

保存后完全退出并重启 Claude Desktop。然后打包 Skill：

cd "$FLYWHEEL_MCP_HOME/skills"
zip -r "$HOME/Desktop/strategic-analytics.zip" strategic-analytics

先在 Claude 的设置中启用 Code execution and file creation。然后在 Customize → Skills → + → Create skill → Upload a skill 上传 ZIP 并启用；Team/Enterprise 也可由管理员在组织 Skills 中统一发布。上传后用一个简单问题同时确认 Skill 被调用且 flywheel_list_analyses 可见。

更完整的联动边界、凭据注入和故障排查说明见 MCP × Skill 联动指南。

5. 可选的 HTTP 服务模式

pnpm dev:http

默认端点为 http://127.0.0.1:3000/mcp，健康检查为 /healthz，Doris 就绪检查为 /readyz。生产或非本机监听必须设置独立的 MCP_API_KEY、SKU_REF_HMAC_SECRET、允许的 Host，并经企业 HTTPS 网关提供服务。

一次标准问数如何执行

例如用户询问：

5 月销量下降主要由哪些站点构成？

执行链路为：

  1. Skill 识别为 growth_driver，指标为 estimated_sales_units；
  2. Skill 从运行时水位确认“5 月”是完整月份；
  3. MCP 校验月份首日边界、对比期和维度；
  4. MCP 分别查询当前期、上期、站点分组和整体值；
  5. 固定场景对齐站点并计算绝对变化、增长率和数学贡献；
  6. Skill 输出“哪些站点构成变化”，但不会声称这些站点是业务变化的因果原因。

真实快照中，这个问题得到的回答包括：2026 年 5 月估算销量环比下降 9.57%，下降主要体现在 US 和 DE 的数学变化，JP 与 cn 提供了部分正向抵消。完整数字、参数和回答见 真实使用案例与回答。

结果契约与安全边界

固定场景统一返回：

  • headline、summary、overall、breakdown 和 chartData；
  • 标准化输入、指标/语义层/场景版本和查询哈希；
  • 数据水位、范围版本、缺失覆盖、Top N 和对账状态；
  • 本币或 CNY 的完整换算 metadata；
  • 方法定义、假设、警告和不可推断边界。

关键保护包括：

  • 指标、维度、过滤器和物理标识符白名单；
  • 服务端 prepared statement 和半开月份区间；
  • 本币跨站点聚合失败关闭；
  • CNY mapping、汇率快照和查询计划 preconditions；
  • 未覆盖月份、对比期为零和空结果不冒充业务零；
  • Top N 之外返回 other 或覆盖率，不静默丢失；
  • 具名品牌过滤必须先搜索；普通品牌分组/排名只允许单月、limit≤20，完整份额、集中度、覆盖、结构变化和数学驱动只通过两个品牌专用场景执行；
  • 品牌专用结果分开具名 Top N、其他具名品牌、来源 OTHERS/其他 与缺失；HHI 按 0–10000 返回安全区间：lowerBound 是具名品牌份额平方和，upperBound 把 source_others + missing 的全部未识别份额并入该期最大具名品牌（该期无具名品牌时视为一个品牌）；跨期结果只描述份额、排名和观察状态变化，不证明消费者在品牌间转移；
  • 价格带只通过固定场景和版本化政策执行；区间左闭右开，跨站点先换 CNY，缺价销量显式单列，调用方不能传自定义边界或在 Host 侧重分桶；
  • 标准类目下钻先读取版本化父子映射，再以 parentFilters + childDimension 或已选 children[].filters 和 standardCategoryMappingPrecondition 执行现有场景；映射中存在但所选期间未观察到的节点回答为不可用，映射外事实或过期快照失败关闭；
  • 平台原始类目必须同时提供单值 platform eq 和 site eq；同名叶子类目以完整路径区分，跨平台比较使用标准类目；
  • SKU 标题不作为身份，粒度冲突返回 SKU_GRAIN_CONFLICT；直接价格不得被再平均，生命周期区间不得解释为精确抓取时点或连续在售时长；当前不提供活跃 SKU 数、上新 SKU 数或其他 SKU 计数指标；
  • 数学贡献不解释为因果，结果不自动生成深度战略建议。

验证

普通 CI 使用：

pnpm check

该命令运行格式检查、TypeScript 类型检查、全部测试和生产构建。真实交付环境还可以执行：

pnpm verify:delivery

verify:delivery 会访问真实 Doris 和 Frankfurter/ECB，验证连接、数据水位、汇率、QueryIntent、10 个大盘场景、SKU 搜索路径、价格带与 CNY 换算。它不会输出业务金额、SKU 身份或连接凭据，也不进入普通离线 CI。

CI 还会在 Node.js 20 与 24 上验证离线交付契约，并执行覆盖率、Markdown 本地链接、Skill 元数据/引用和 npm pack 内容门禁。docs/usage-examples.md 包含仅限私有仓库的受控真实聚合案例，供同事理解最终回答；它不会进入 npm pack 运行工件，也不得复制到公开 Release 说明。

项目结构

.
├── config/                         # 语义层、币种/价格带与标准类目治理源
├── docs/                           # 用户、架构、治理和案例文档
├── skills/strategic-analytics/     # Host 侧分析 Skill
├── src/analysis/                   # QueryIntent、实体与时间标准化
├── src/catalog/                    # 语义层加载与公开目录
├── src/currency/                   # CNY mapping 与 ECB 汇率快照
├── src/price-band/                 # 价格带政策契约、校验和快照身份
├── src/query/                      # 查询契约、安全编译和执行
├── src/scenarios/                  # 11 个固定业务场景和共享算子
├── src/sku/                        # SKU 搜索、签名引用和私有计划
├── src/mcp/                        # MCP 工具与输出契约
├── tests/                          # 单元、黄金集、合约和生命周期测试
├── AGENTS.md                       # Codex 项目指令
└── CLAUDE.md                       # Claude Code 项目指令

当前边界与后续方向

当前不支持任意 SQL、消费者在品牌间的转移识别、因果品牌驱动、跨平台公司主数据级品牌身份合并、店铺分析、商品级聚合、批量 SKU、跨 SKU 排名、SKU 级 CNY、调用方自定义价格带、活跃/上新 SKU 数、价格弹性、因果分析、预测和自动战略建议。已搜索并确认的标准品牌标签可过滤；普通品牌列表受单月 Top 20 约束，完整份额/集中度/覆盖/数学驱动由专用场景支持。

下一阶段优先事项是专用只读 Doris 账号、内网 DNS 与 TLS、查询压测和监控，以及为商品聚合和多月价格带等能力建立标准化与性能边界。多用户身份认证不属于当前阶段范围，但共享 API Key 不能被描述为员工级授权。

开发与治理

  • 指标与币种确认负责人：陈煜-战略分析师（Fika chen）；
  • 不兼容口径变更必须提升版本并同步 MCP、语义层、Skill、测试和文档；
  • 代码代理应先阅读 AGENTS.md 或 CLAUDE.md，不要把本 README 当作开发指令；
  • 上线前按 生产上线清单 完成环境侧验收。

About

Governed Doris market analytics MCP and Strategic Analytics Skill for safe natural-language analysis

Topics

typescript analytics mcp apache-doris agent-skills

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

2 forks
Report repository

Releases 2

Flywheel MCP 0.7.0 Latest
Jul 13, 2026
+ 1 release

Packages

 
 
 

Contributors

Languages