Cerebro MCP

脑MCP

Cerebro MCP

用于ClickHouse和dbt之上的Gnosis链分析的模型上下文协议服务器。

Cerebro MCP向MCP主机（如Claude Desktop、Claude Code和VS Code）提供查询、模式、可视化、报告和长期研究工具。它针对三种不同的使用模式而设计：

1. 快速探索性分析和事实查找
2. 交互式图表和报告生成
3. 持久、分阶段驱动的研究项目

此README是有意面向实现的。它描述了服务器今天实际做了什么，MCP流是如何工作的，以及每个作业使用哪些工具。

______________________________________________________________________

Cerebro MCP到底是什么

Cerebro MCP是一个FastMCP服务器，具有：

• ClickHouse访问只读SQL
• dbt清单搜索和沿袭查找
• 交互式图表和报告生成
• 推理/跟踪实用程序
• 持久研究项目存储
• 从YAML配置加载的参数化自定义查询工具
• 用于指标仪表板的AI仪表板选项卡脚手架
• 在报告之前检查算术和交叉引用的数字验证工具
• MCP提示和资源指导客户端，但不会自动运行
• 具有工具风险分类、可疑呼叫检测和仅附加JSONL日志的安全审计层
• 五个React+ECharts 迷你应用程序 （报告、度量实验室、投资组合、图形资源管理器、合约资源管理器）通过以下方式作为单个文件HTML ui://cerebro/ 资源--请参见 docs/MINI_APPS.md 全程游览
• 直接JSON-RPC读取EVM合约(contract_explore, contract_call_function, contract_decode_transaction_input, contract_decode_receipt_logs)--支持Contract Explorer迷你应用程序，是 *单地址当前状态* （相对于dbt的扫描/历史/美元）

重要区别：

• 工具在服务器上执行逻辑
• 提示向客户返回指导文本
• 资源公开静态参考资料
• 服务器不运行内部自主LLM循环

如果客户想要使用角色或同行评审，它必须明确调用支持它的提示或工具流。

______________________________________________________________________

特工舰队

Cerebro搭载 27个代理角色 可装载过孔 get_agent_persona(role)它们是即时层指导——LLM在任务期间采用角色的规则，然后可以切换。人物角色分为三个层次：

第1层——顶级编排器

第2层——工作流程负责人

第3级——领域专家（根据需要咨询）

门控： 当调度器发出列出所需专家的清单时，会话将其视为具有约束力的执行契约。MMM流硬块 generate_report 直到 mmm_causal_reviewer 回报 VERDICT: PASS故事讲述者的流程会严格阻止最终的切换，直到每个清晰度检查都通过。看 docs/cerebro docs--MCP/代理 对于完整的代理目录、门语义和路由表。

______________________________________________________________________

MCP的工作原理

在运行时，系统看起来像这样：

1. 您的MCP主机通过以下方式连接 stdio 或 SSE
2. 主持人要求模型解决一个任务
3. 模型从该服务器中选择工具、提示和资源
4. 服务器执行ClickHouse/dbt/report/research逻辑并返回结构化数据
5. 对于报告工具，MCP App兼容客户端可以呈现返回的 structuredContent 内联

核心运行时组件：

• clickhouse_client.py：共享执行管道、限制强制、JSON安全规范化、模式缓存
• tools/query.py：同步SQL执行
• tools/query_async.py：具有分页结果预览的异步查询作业
• tools/schema.py：表列表和模式检查
• tools/dbt.py：模型搜索和沿袭/上下文查找
• tools/visualization.py：图表注册表、报表呈现、报表持久化
• tools/research.py：持久的研究项目、证据、验证、同行评审、出版
• tools/mini_apps.py：迷你应用视图基础架构，仅应用工具可见性过滤器
• tools/metric_lab.py：交互式公制实验室视图
• tools/contract_explorer.py：交互式合约资源管理器视图（ABI解析、视图调用、解码）
• tools/rpc.py：独立RPC工具(contract_explore, contract_call_function, contract_decode_*)
• security.py：工具风险分类，可疑调用标记，仅附加JSONL安全审计日志
• observability.py：Prometheus指标、结构化JSON日志记录、安全计数器

服务器创建的工件：

• 保存在磁盘上的报告
• 已保存的查询SQL代码段
• 异步查询结果页面
• 研究项目和证据快照
• 推理痕迹
• 安全审计日志（JSONL，每日轮换）

______________________________________________________________________

选择正确的工作流

当您不需要图表或持久状态时，请使用快速浏览。当可交付成果是视觉工件时，使用报告。当工作跨越多个阶段或需要明确的证据和审查时，使用研究。

______________________________________________________________________

端到端工作流

1.探索性聊天

当用户询问以下问题时，请使用此选项：

• “昨天有多少笔交易？”
• “哪些表涵盖了验证器活动？”
• “比较过去7天的桥梁流入量”

推荐顺序：

1. 查找正确的数据源

- 更喜欢 discover_models(query, detail_top_n=5) 作为第一步 - 使用 search_models + get_model_details 只有当你想要更广泛的人工分诊时

1. 验证实际架构

- 呼叫 describe_table 在编写SQL之前

1. 运行有界查询

- 使用 execute_query - 使用 explain_query 首先，如果您不确定SQL形状

1. 如果查询量大或速度慢

- 使用 start_query - 投票与 get_query_results

最小模式：

discover_models("bridge volume daily", detail_top_n=5)
describe_table("api_bridges_volume_daily", database="dbt")
execute_query("SELECT dt, volume_usd FROM dbt.api_bridges_volume_daily WHERE dt >= today() - 7 ORDER BY dt", database="dbt", max_rows=30)

期待什么 execute_query:

• 结构化有效载荷 columns, rows, row_count, rows_returned, warnings
• summary_markdown 用于人类可读的表格
• 自动行和有效载荷截断以保护MCP/LLM上下文

何时改用async：

• 预期结果集很大
• 查询可能需要比正常聊天时间更长的时间
• 您需要分页结果检索

异步流：

start_query(...)
get_query_results(query_id)
get_query_results(query_id, page_token="...")

重要行为：

• 异步作业是进程内的，不是永久的
• 重新启动服务器会丢失挂起/完成的异步作业状态
• 在短暂的保留期后，已完成的异步作业将被清理

1b。语义分析工作流程

当用户真正询问一个受管的度量问题时，请使用此选项，例如：

• “按部门显示过去30天的交易计数”
• “我可以按哪些维度对验证器奖励进行切片？”
• “解释如何计划此指标查询”

推荐顺序：

1. 探索公制曲面

- 呼叫 discover_metrics(query, module=..., limit=...)

1. 检查已解决的指标

- 呼叫 get_metric_details(metric_name)

1. 当路径不平凡时，在执行前进行解释

- 呼叫 explain_metric_query(...)

1. 通过语义层执行

- 呼叫 query_metrics(...)

1. 如果语义执行不可用或不受支持

- 显示返回的回退原因 - 使用以下命令迁移到原始SQL describe_table, get_model_details, execute_query，以及 get_clickhouse_query_rules

重要行为：

• 语义执行由以下因素控制部署 SEMANTIC_ENABLED
• 当启用语义但工件过时或不可用时，语义工具会保持注册状态，但执行会返回优雅的不可用指导
• query_metrics 对已知的安全ClickHouse错误执行一次确定性服务器端修复重试
• 原始 execute_query 仍然由代理引导，而不是由服务器自动修复

1c。自定义参数化查询

当用户询问具有已知参数的常见域问题时，请使用此选项：

• “验证器12345的余额历史记录是什么？”
• “显示0x的GNO传输…”
• “USDC的过桥流量是多少？”

这些是预先构建的、经过同行评审的SQL模板。LLM传递类型化参数；ClickHouse以本机方式处理绑定。零SQL幻觉风险。

推荐顺序：

1. 检查可用工具

- 呼叫 list_custom_tools 查看可用的参数化工具

1. 直接调用匹配工具

- 例如 get_validator_balance_history(validator_index=12345, start_date="2025-01-01")

示例工具：

get_validator_balance_history(validator_index=12345, start_date="2025-01-01")
get_token_transfers_for_address(address="0x...", token_symbol="GNO")
get_bridge_flows_by_token(token="USDC", start_date="2025-06-01")
get_gpay_wallet_activity(wallet_address="0x...")

自定义工具使用ClickHouse本机参数绑定({param:Type})并且对SQL注入免疫。当不存在自定义工具时，退回到原始SQL工作流。

1d。号码验证

这 verify_numbers 该工具在数字到达用户之前捕获计算错误。代理必须显示它的工作——它使用的公式和组件值——这样工具就可以独立地验证数学。

何时调用：在报告任何计算数字（总和、净值、百分比、总计）之前。

它是如何工作的：

1. 代理根据查询结果计算数字
2. 客服电话 verify_numbers 结构化索赔：

- label：这个数字代表什么 - value：计算出的数字 - formula：使用的算术（例如，“接收-发送”） - components：命名值（例如，{“收到”：9352.5，“发送”：9002.9}） - check_query：针对独立模型的可选SQL，用于交叉引用

1. 工具验证：收到-发送的值是否等于声称的值？
2. 工具运行check_query（如果提供）并进行比较
3. 返回带有特定错误详细信息的“通过”或“不匹配”

捕获一个真实错误的示例：

代理人计算了转账并声称净流入=1360 GNO：

verify_numbers('[{"label": "net GNO inflow", "value": 1360.5, "formula": "received - sent", "components": {"received": 9352.5, "sent": 9002.9}}]')

结果：算术失败--9352.5-9002.9=349.6，而非1360.5（差异：289.2%）。在呈现给用户之前，代理必须更正为349.6。

2.报告工作流程

当用户需要时使用此功能：

• 每周或每月的总结
• 图表、趋势、仪表板或视觉比较
• 可以重新打开或导出的报表工件

推荐顺序：

1. 发现相关模型

- 更喜欢 discover_models(query, detail_top_n=5)

1. 使用验证真实表 describe_table
2. 使用以下命令运行探索性查询 execute_query
3. 构建图表

- 首选： generate_charts - 次要： generate_chart - 对于没有大门的一次性地块： quick_chart

1. 用图表占位符写标记
2. 呼叫 generate_report
3. 可选使用 open_report, list_reports，或 export_report

首选报告图表流程：

generate_charts([
  {...},
  {...},
  {...}
])
generate_report(title="Gnosis Chain Weekly Report", content_markdown="...")

使用哪种图表工具

报告标记语法

报告呈现器理解：

• ## Heading 主要路段
• {{chart:chart_id}} 放置图表
• {{grid:N}} ... {{/grid}} 将图表分组到网格行中

例子：

## Executive Summary

{{grid:3}}
{{chart:chart_1}}
{{chart:chart_2}}
{{chart:chart_3}}
{{/grid}}

Key takeaways from the week.

## Activity Trend

{{chart:chart_4}}

## Breakdown

{{grid:2}}
{{chart:chart_5}}
{{chart:chart_6}}
{{/grid}}

实际执行与推荐的内容

图表创建的硬门：

• generate_chart 和 generate_charts 要求：

- 至少一次发现调用(search_models 或 discover_models) - 至少 MIN_MODELS_DETAILED 模型细节探索 - 至少 MIN_TABLES_VERIFIED 表架构检查

创建报告的硬门：

• 至少 MIN_CHARTS_FOR_REPORT 注册图表
• 至少一个趋势图或细分图
• 至少 MIN_EXPLORATORY_QUERIES 之前的查询执行
• 至少一维分解
• 至少一个关系分析信号：

- 散点图或热图，或 - 相关性查询

仅软警告：

• 缺乏统计查询
• 缺乏明确的相关性/回归查询
• 制图前浅层勘探
• 较大的报告中没有散点图

布局执行：

• 如果报告包含两个或多个 numberDisplay 图表和否 {{grid:N}} 块，报告生成被拒绝
• 其他布局指导是通过提示和角色推荐的，但不会被渲染器硬屏蔽

这很重要，因为旧文档可能意味着比服务器实际执行的布局或角色执行更严格。

报告输出

generate_report 做三件事：

• 将独立的HTML报告保存到磁盘
• 回报 structuredContent 适用于支持MCP应用程序的客户端
• 返回包含报告ID和重新打开/导出提示的文本摘要

创建后有用的报告工具：

• open_report(report_id) 重新打开已保存的报表
• list_reports() 浏览已保存的报告
• export_report(report_id) 获取文件路径或SSE下载URL

3.研究工作流程

当用户需要时使用此功能：

• 深入调查
• 多匝多相分析
• 持久记忆和证据
• 明确验证和同行评审

研究系统是MCP本地和客户端编排的。它不是一个自主的背景科学家。助理必须明确地推动项目的各个阶段。

研究阶段：

1. mapping
2. hypothesis
3. execution
4. verification
5. publication

推荐顺序：

start_research_project(...)
plan_research_phase(..., phase="mapping")
execute_research_phase(..., phase="mapping")
capture_schema_snapshot(...)
record_research_memory(...)

plan_research_phase(..., phase="hypothesis")
execute_research_phase(..., phase="hypothesis")

plan_research_phase(..., phase="execution")
execute_research_phase(..., phase="execution")
execute_query(..., research_project_id=..., persist_result=True)
attach_research_evidence(...)
record_research_finding(...)

verify_research_phase(...)
prepare_peer_review(...)
conduct_research_peer_review(...)
record_peer_review(...)
publish_research_report(...)

研究项目行为

get_research_project(project_id) 仅返回简洁摘要：

• 当前阶段
• 状态
• 证据清点
• 存储器计数
• 调查结果统计
• 同行评审状态
• 人工制品计数

有关详细信息，请使用分页检索工具：

• get_research_memory
• get_research_evidence
• get_research_findings

研究证据规则

持久证据种类：

• query_result
• semantic_query_result
• schema_snapshot
• chart
• report

重要提示：

• save_query 不是证据
• save_query 仅存储可重用的SQL
• 持久同步查询证据必须来自 execute_query(..., persist_result=True)

跑步时：

execute_query(
  sql=...,
  research_project_id="rp_...",
  persist_result=True,
  evidence_title="Daily bridge volume",
  persist_max_rows=10000
)

服务器执行两项独立的操作：

• 将工具预算的预览有效负载返回给模型
• 在磁盘上存储更大的持久结果工件并返回 result_ref_id

然后，您可以将该结果附加到项目中：

attach_research_evidence(
  project_id="rp_...",
  kind="query_result",
  ref_id="qry_...",
  phase="execution"
)

研究记忆与发现

使用 record_research_memory 对于可重用的域事实：

• 小数和单位
• 关于桌子的注意事项
• 连接约束
• 协议特定注释

使用 record_research_finding 对于特定项目的索赔：

• “方案X后桥梁流入量增加”
• “验证器计数中位数保持稳定”

验证和同行评审

verify_research_phase 这是一种结构检查。它验证以下内容：

• 执行证据存在
• 证据集中存在统计深度
• 证据引用解析清晰

如果验证失败，发布将被阻止。

同行评审明确以客户为导向：

1. 呼叫 prepare_peer_review
2. 将数据包送入 conduct_research_peer_review(packet_json)
3. 呼叫 record_peer_review

审查结果的结构和存储方式为 PeerReviewResult.

出版研究

publish_research_report 重用正常的报告呈现器，但应用研究阶段门控而不是报告模式会话门控。

在以下情况下使用：

• 验证通过
• 同行评审已记录
• 同行评审决定不是 rejected

4.仪表板选项卡工厂

当您需要在指标仪表板Vite应用程序中创建新的仪表板选项卡时，请使用此选项。

推荐顺序：

1. 发现可用指标

- 呼叫 discover_dashboard_metrics(module="bridges") 浏览api\_\*型号

1. 构建蓝图

- 使用选项卡配置和查询规范构建DashboardBlueprint JSON

1. 预览更改

- 呼叫 scaffold_dashboard_tab(blueprint_json) 随着 dry_run: true

1. 应用更改

- 再次致电 dry_run: false 编写JS查询文件并合并YAML配置

脚手架工具在以下位置生成JS查询文件 metrics-dashboard/src/queries/ 并将选项卡配置合并到相应的YAML仪表板文件中。它是幂等的：重新运行会更新现有文件，而不是创建重复文件。

重要提示：LLM从不直接编写React/JSX。只有脚手架工具从Pydantic验证的结构化JSON蓝图生成UI代码。

5.故事讲述者工作流程

当用户明确要求 故事、叙述、执行简报、决策备忘录、利益相关者推销或推荐工件 --任何必须让观众行动起来而不仅仅是展示数据的东西。做 不 自动将标准报告请求升级为说书程序运行；如果用户要求“报告”，但范围不明确，请询问他们想要哪种模式。

故事讲述者是一个基于Cole Nussbaumer Knaflic的选择加入、多代理管道 *用数据讲故事* （威利，2015）。它与标准报告工作流程并排放置，然后离开 generate_report 原封不动。标准模式仍然是仪表板、KPI包、趋势报告和即席分析的默认模式。

为什么它存在

标准报告模式的答案是“向我展示数据”。故事讲述者模式的答案则是“说服这个特定的受众采取这个特定的行动”。这两种模式有不同的形状：

• 标准模式以发现/EDA门允许的最快速度推送图表。
• 故事讲述者模式拒绝接触数据，直到它有一个指定的受众、一个必需的行动和一个有利害关系的一句话的大想法。

如果用户没有指定决策者和具体的问题，讲故事的人会停下来问——猜测观众是决策沟通中最常见的失败模式。

代理管道

故事讲述者由七个合作角色组成，由一个编排者协调。每个角色都有一个狭义的契约，产生一个特定的工件，然后移交给下一个。盖茨是用代码强制执行的(storyteller_state.py)，不是按照惯例——跳过大门会加薪 RuntimeError.

┌────────────────────┐
│    Orchestrator    │  Mode selection + gate enforcement (no content)
└─────────┬──────────┘
          │
┌─────────▼──────────┐
│   Context Agent    │  audience, required action, mechanism, tone
└─────────┬──────────┘  produces: ContextBrief
          │
┌─────────▼──────────┐
│      Explorer      │  runs through standard Cerebro tools
└─────────┬──────────┘  produces: candidate findings (feed, never shipped)
          │
┌─────────▼──────────┐
│  Narrative Agent   │  one-sentence big idea with stakes
└─────────┬──────────┘  produces: BigIdea, Storyboard (setup → tension → resolution)
          │
┌─────────▼──────────┐
│  Visual Designer   │  relationship-first chart choice, one focal point per scene
└─────────┬──────────┘  produces: VisualSpec per scene (action titles, de-emphasis)
          │
┌─────────▼──────────┐
│       Writer       │  action titles, annotations, prose, medium adaptation
└─────────┬──────────┘  produces: final_story markdown with chart placeholders
          │
┌─────────▼──────────┐
│       Critic       │  adversarial, cold-reader review (four clarity tests)
└─────────┬──────────┘  produces: ReviewReport (ready_for_handoff + blocking_issues)
          │
┌─────────▼──────────┐
│  Accessibility &   │  colorblind palette, contrast, language, tone match
│    Tone Agent      │
└─────────┬──────────┘  produces: pass/fail verdict
          │
┌─────────▼──────────┐
│      Handoff       │  storyteller_generate_story_report
└────────────────────┘  renders via the existing generate_report pipeline

每支箭都是一道坚硬的门。在评论家失败时，管道会循环回到与阻塞问题有关的最早阶段（失败的反向故事板会将作品发回叙事，而不是编剧）。

为什么是七个角色，而不是一个像巨石一样的角色 analytics_reporter？讲故事的人是 伪影切换流水线 --每个阶段都会产生一个类型化的Pydantic工件，下一阶段将其作为整个输入消耗。人物角色分离符合真实的信息边界：评论家必须冷静地阅读作品，没有作家的“美化”偏见。分析记者是 国家积累管道 在后面的阶段需要完整的上游历史，因此单片是正确的。不同的形状，不同的布局。

工作流程

1. storyteller_start_session
2. get_agent_persona("storyteller_orchestrator") and ("storyteller_context")
3. Collect audience, required action, mechanism, tone, background, biases
4. storyteller_record_context_brief(...)         # Gate 1: context
5. Explore data with standard Cerebro tools (discover_models, execute_query, etc.)
6. get_agent_persona("storyteller_narrative")
7. storyteller_record_big_idea(sentence, stakes) # Gate 2: big idea
8. storyteller_record_storyboard(scenes, ...)    # Gate 3: storyboard
9. get_agent_persona("storyteller_visual_designer")
10. storyteller_record_visual_spec(scene_index, ...)   # one per scene
    generate_charts([...])                             # render via standard tool
    storyteller_record_visual_spec(..., chart_id=...)  # attach chart_id
11. get_agent_persona("storyteller_writer")
12. storyteller_record_final_story(title, content_markdown)  # Gate 4: final story
13. get_agent_persona("storyteller_critic")
14. storyteller_run_clarity_checks(checks=[...])  # Gate 5: clarity review
    # On failure: loop back to earliest failing phase
15. get_agent_persona("storyteller_accessibility")
16. storyteller_record_accessibility_pass(passed, notes)  # Gate 6: accessibility
17. storyteller_generate_story_report()          # renders via generate_report

调用LLM遵循的最小模式：

storyteller_start_session()
storyteller_record_context_brief(
  audience="Q2 budget committee",
  required_action="Approve $250k to continue the summer pilot next year",
  mechanism="memo",
  tone="recommendation"
)
# ... normal Cerebro discovery, EDA, correlation queries ...
storyteller_record_big_idea(
  sentence="The pilot lifted perception of science by 28 points, so the committee should fund a full-year rollout."
)
storyteller_record_storyboard(
  scenes=[
    {"index": 0, "intent": "Set up the pilot's goal", "role": "setup"},
    {"index": 1, "intent": "Show the pre-pilot baseline gap", "role": "tension"},
    {"index": 2, "intent": "Show the 28-point lift", "role": "evidence"},
    {"index": 3, "intent": "Ask for full-year funding", "role": "resolution"},
  ],
  narrative_order="lead_with_ending"
)
# ... record one visual_spec per scene; render charts via generate_charts ...
storyteller_record_final_story(title, content_markdown)
storyteller_run_clarity_checks(checks=[...])
storyteller_record_accessibility_pass(passed=True)
storyteller_generate_story_report()

大门强制执行什么

• 上下文门。 像“利益相关者”或“领导层”这样的模糊受众在Pydantic层被拒绝。少于10个字符的所需操作将被拒绝。机制必须是以下之一 live_presentation, slide_deck_leave_behind, emailed_deck, memo, brief, dashboard_excerpt, script.
• 大创意之门。 必须是一个完整的陈述句，有观点和利害关系。标签（“Q3收入”）、单个单词和以冒号结尾的字符串将被拒绝。
• 故事板门。 必须至少包含一个 tension 场景和至少一个 resolution 现场。平淡的“一切都很好”的叙述被拒绝了。
• 视觉规格门。 pie, donut, 3d，以及 dual_axis 图表族被拒绝。动作标题必须是句子，而不是标签。每个场景索引都必须与录制的故事板中的一个场景相匹配。
• 清晰度审查门。 ready_for_handoff 是 True 只有通过所有清晰度检查。故障会使管道退回到最早的故障阶段，并通过 blocking_issues 列表。
• 无障碍门。 硬故障（色盲敌对编码、不可读对比度）会阻止切换。软故障会发出警告，但不会阻止。

所有的门都是代码，不是惯例。相关模块包括：

• src/cerebro_mcp/storyteller_models.py --Pydantic合约和验证器
• src/cerebro_mcp/storyteller_state.py --相位光标和门强制
• src/cerebro_mcp/tools/storyteller.py --11个MCP工具

与标准模式的关系

讲故事的人会 不 替换标准报告管道。两种模式并存：

• 标准模式（默认）： discover_models → execute_query → generate_charts → generate_report.不变。
• 故事讲述者模式（选择加入）：用门控角色切换包裹标准管道。 storyteller_generate_story_report 通过相同的方式渲染最终工件 create_report_artifact 被...使用 generate_report，但绕过了标准的质量门，因为讲故事的人有自己的质量门。

标准会话状态(search_models_count, explored_models，图表注册表）在故事讲述者运行中保留，这样用户就可以在故事呈现后继续探索。

不要自动升级。如果用户问“给我一份关于桥梁活动的报告”，问他们是想要一份标准报告还是一份以决策为导向的故事。

6.MMM工作流程

当用户询问以下内容时使用此选项 贡献归因、激励计划的投资回报率、预算优化，或“哪些排放/奖励实际上推动了TVL/数量/用户”.MMM（营销组合建模）使博报堂/谷歌框架适应链上激励：媒体=代币排放/LM奖励/验证器APR，KPI=TVL/DEX量/DAU/tx计数。

MMM是一个 门控的 工作流程。 generate_report 被封锁，直到 mmm_causal_reviewer 回报 VERDICT: PASS该门捕捉到了最常见的MMM故障模式——未被发现的混淆（例如，用户增长同时驱动激励和KPI），否则这些混淆会将真正的驱动因素低估一个数量级。

工作流程

1. get_agent_persona("mmm_analyst")
   - Runs the full SOP: spine-fill → multicollinearity → baseline → adstock → concave + Hill fit → decompose
   - SQL toolkit is in the persona (geometric adstock, Hill grid search, bootstrap CIs, etc.)
   - Requires ≥60 weekly rows or downgrades output to "directional only" with a banner
2. Synthesize mmm_analyst's output into a markdown DAG table (nodes, edges, confounder flags)
3. get_agent_persona("mmm_causal_reviewer")
   - Pass the DAG table verbatim as the next user message
   - Reviewer runs three checks: chronological, non-inclusion, identifiability
   - On BLOCK: apply the prescribed fix (intervention / segmentation / front-door variable), re-submit
4. On PASS verdict:
   - generate_charts (batch): contribution stacked-area, spend-vs-effectiveness share,
     response-curve scatter per media, adstock decay, plus the causal-review markdown table
   - generate_report
5. Optional prescription step (if user asks "what should we do next?"):
   - get_agent_persona("mmm_simulator")
   - Pass fitted (β, r, λ, current_spend, baseline_kpi) per media
   - Simulator caps any shift at ±30%/period and returns marginal-ROI + reallocation charts

什么 mmm_causal_reviewer 捕获

该审查是强制性的，因为一个打开的后门可以翻转系数的标志（博报堂指南第35-38页）或将驾驶员的属性降低约9.8倍（指南第116页，归因模拟下的电视）。审阅者标记的常见链上故障：

• 反向因果关系：使用按绩效付费的支出作为转换的原因——箭头指向相反的方向
• 根据结果循环计算：当APR来自存款量时，使用验证器APR作为存款原因
• 共同发起混淆：同一周开始的两个激励计划具有相关序列——如果没有干预、细分或前门中间环节（例如唯一的钱包计数），模型无法将它们分开

按优先级顺序规定的修复：（1）交错/黑暗期干预，（2）受众或协议分割，（3）前门变量，（4）未来黑暗期请求。

MMM报告中所需的图表

在标准之上 generate_report 门，MMM报告必须包括：

• 随时间变化的贡献堆叠面积（series_field=media）
• 支出与效率份额（分组栏）
• 每种介质的响应曲线（散点+拟合线）
• 每种介质的广告衰减显示λ
• 因果关系审查表（降价，来自 mmm_causal_reviewer)

看 docs/cerebro docs-MCP/MMM 对于完整的SQL工具包，在真实的Gnosis App数据上的工作示例，以及通过实时冒烟测试发现的4个SQL错误（带有补丁片段）。

7.MTA+统一测量工作流程

当用户询问以下内容时使用此选项 用户旅程归因、观察到的接触点路径、“哪些应用程序操作在X之前”或者，当与MMM结合使用时，将宏观提振与微观接触点信贷相协调。MTA（多点触控归因）是MMM的旅程谷物、观察补充。

统一堆栈基于一个规则：

MMM estimates the incremental pie.
MTA divides the observed, trackable slice of that pie.
Experiments give the strongest causal validation.

MTA 不能 创造超越MMM的升力；它只能在MMM内进行分配。当MTA与MMM并行运行时 unified_causal_reviewer 在报告发布之前，检查八个条件（MMM门通过、转换一致性、增量界限、覆盖披露、泄漏、身份粒度、选择偏差、方法稳定性），并应用校准 calibrated_credit_i = raw_credit_i × MMM_lift / Σ raw_credit 因此，MTA的股价受到MMM估计涨幅的限制。MMM升降机中没有观察到的接触点可以声称的部分在报告中显示为 unexplained / untracked.

工作流程

1. get_agent_persona("mta_analyst")
   - Discovery-first: search_models / discover_models, then describe_table on every model used
   - Build a runtime mapping (user_id, timestamp, touchpoint, conversion, identity grain)
   - Default lookback 30 days (sweep 7/14/30/60 when volume permits)
   - Volume gates: ` 默认情况下
- `/health` 是公开的
- `/reports/{id}` 接受承载认证或 `?token=...`

要禁用仅用于本地测试的身份验证，请执行以下操作：

ALLOW_INSECURE_REMOTE_TRANSPORT=True

### 使用Docker运行

构建：

docker build -t cerebro-mcp .

运行：

docker run \ --env-file .env \ -p 8000:8000 \ -v "$(pwd)/data:/data" \ cerebro-mcp

对Docker很重要：

- 图像使用 `/data` 用于持久存储
- 安装 `/data` 容器用户必须可写 `uid 1000`
- 报告、保存的查询、日志和研究项目都位于 `/data` 在图像默认值中
- 如果使用本地语义工件路径而不是已发布的URL，请将这些文件装载到容器中并指向相应的 `*_PATH` 安装位置的设置

______________________________________________________________________

## 连接MCP客户端

### 克劳德桌面版

如果 `cerebro-mcp` 在你的 `PATH`:

{ "mcpServers": { "cerebro": { "command": "cerebro-mcp", "env": { "CLICKHOUSE_PASSWORD": "your_password", "CEREBRO_RESEARCH_DIR": ".cerebro/research_projects" } } } }

### 克劳德代码

使用 `uv` 从已签出的repo中：

{ "mcpServers": { "cerebro": { "command": "/path/to/uv", "args": ["--directory", "/path/to/cerebro-mcp", "run", "cerebro-mcp"] } } }

### VS Code

{ "servers": { "cerebro": { "command": "/path/to/uv", "args": ["--directory", "/path/to/cerebro-mcp", "run", "cerebro-mcp"] } } }

### 远程SSE客户端

{ "mcpServers": { "cerebro": { "url": "https://mcp.analytics.gnosis.io/sse", "headers": { "Authorization": "Bearer " } } } }

______________________________________________________________________

## 部署说明

### 健康端点

`/health` 执行真正的ClickHouse连接检查并返回：

- `200` 当ClickHouse可访问时
- `503` 当ClickHouse无法访问时
- `clickhouse_version`
- `ssl_trust_injected`

### 报告下载端点

在SSE模式下：

GET /reports/{report_id}

行为：

- 接受完整的UUID或唯一的短前缀
- 返回独立HTML
- 支持承载头或 `?token=...`

### 清单和文档加载

启动时，服务器尝试加载：

- dbt清单
- dbt目录
- 启用语义时的语义注册表
- 启用语义时的语义文档索引
- 外部文档索引

如果这些失败，dbt和文档辅助功能会降低，但服务器仍然可以启动。

语义特定行为：

- 语义加载仅发生在 `main()`，不是在导入时
- 当语义注册表哈希相对于清单或目录过时时，语义执行将被禁用，但语义发现/文档仍然可用
- 语义快照重新加载发生在线程外，运行时在锁下切换到新快照

对stdio客户端很重要：

- MCP传输期望JSON-RPC在 `stdout` 仅
- 任何发送到的纯文本启动日志 `stdout` 将断开连接
- Cerebro通过日志记录/stderr发送启动诊断

### 供应商ClickHouse代理技能

`get_clickhouse_query_rules` 故意严格。仅当有效的供应商捆绑包存在时，才会注册 `CLICKHOUSE_AGENT_SKILLS_PATH`.

规范同步流为：

python scripts/sync_clickhouse_skills.py /path/to/local/agent-skills-checkout --ref

同步脚本仅复制所需的上游内容：

- `skills/clickhouse-best-practices/**`
- `LICENSE`
- `NOTICE`
- 本地人 `bundle_manifest.json` 包含固定源引用和确定性编译规则路径

只要操作员提供上游仓库的本地签出，实现环境就可以保持离线。服务器将不会注册 `get_clickhouse_query_rules` 从部分复制的目录中。

______________________________________________________________________

## 配置

所有设置都是环境变量或 `.env` 价值观。

### dbt与语义伪影

|变量|默认值|描述|
|---|---|---|
| `DBT_MANIFEST_URL` |出版 `dbt-cerebro` 清单URL|远程清单源；优先于本地路径|
| `DBT_MANIFEST_PATH` |空|本地清单回退|
| `DBT_CATALOG_URL` |出版 `dbt-cerebro` 目录URL|远程目录源；优先于本地路径|
| `DBT_CATALOG_PATH` |空|本地目录回退|
| `DOCS_BASE_URL` | `https://docs.analytics.gnosis.io/` |用于派生的规范文档宿主 `llms.txt`, `llms-ctx*.txt`，以及页面镜像URL|
| `DOCS_SEARCH_INDEX_URL` |已发布文档搜索URL |外部平台文档索引|
| `DOCS_SEARCH_INDEX_PATH` |空|本地文档索引回退|
| `DOCS_REFRESH_INTERVAL_SECONDS` | `3600` |文档索引刷新节奏|
| `GNOSIS_CHAIN_DOCS_LLM_URL` | `https://docs.gnosischain.com/llms.txt` |Gnosis Chain文档上下文工件用于搜索和宽链上下文|
| `SEMANTIC_ENABLED` | `False` |部署级语义切换；唯一的语义开/关控制|
| `SEMANTIC_REGISTRY_URL` |出版 `dbt-cerebro` 注册表URL|远程语义注册表源|
| `SEMANTIC_REGISTRY_PATH` |空|本地语义注册表回退|
| `SEMANTIC_DOCS_INDEX_URL` |出版 `dbt-cerebro` 语义文档URL|远程语义文档索引源|
| `SEMANTIC_DOCS_INDEX_PATH` |空|本地语义文档索引回退|
| `SEMANTIC_REFRESH_INTERVAL_SECONDS` | `300` |语义快照刷新节奏|
| `CLICKHOUSE_AGENT_SKILLS_PATH` | `src/cerebro_mcp/static/clickhouse_agent_skills` |供应商ClickHouse规则捆绑包根|

### 仪表板生成器和自定义工具

|变量|默认值|描述|
|---|---|---|
| `DASHBOARD_BUILDER_ENABLED` | `False` |启用仪表板脚手架工具|
| `METRICS_DASHBOARD_PATH` |空|指标仪表板仓库根的绝对路径|
| `CUSTOM_TOOLS_ENABLED` | `False` |启用YAML定义的参数化查询工具|
| `CUSTOM_TOOLS_PATH` |空| custom_tools.yaml配置文件的路径|

### ClickHouse和SQL限制

|变量|默认值|描述|
|---|---|---|
| `CLICKHOUSE_HOST` | `ujt1j3jrk0.eu-central-1.aws.clickhouse.cloud` |ClickHouse服务器|
| `CLICKHOUSE_PORT` | `8443` |ClickHouse端口|
| `CLICKHOUSE_USER` | `default` |ClickHouse用户|
| `CLICKHOUSE_PASSWORD` |空| ClickHouse密码|
| `CLICKHOUSE_SECURE` | `True` |使用TLS|
| `CLICKHOUSE_VERIFY` | `True` |验证TLS证书|
| `CLICKHOUSE_CONNECT_TIMEOUT` | `30` |连接超时|
| `CLICKHOUSE_SEND_RECEIVE_TIMEOUT` | `300` |套接字超时|
| `CLICKHOUSE_QUERY_TIMEOUT_SECONDS` | `30` |服务器端执行超时|
| `QUERY_TIMEOUT_SECONDS` | `30` |已弃用回退|
| `MAX_ROWS` | `10000` |内部执行的最大查询结果行数|
| `MAX_QUERY_LENGTH` | `10000` |最大可接受SQL长度|

### 工具响应预算

|变量|默认值|描述|
|---|---|---|
| `TOOL_RESULT_MAX_ROWS` | `200` |返回给同步工具使用者的最大行数|
| `TOOL_RESULT_MAX_CHARS` | `40000` |最大序列化同步工具有效负载大小|
| `TOOL_SUMMARY_BUDGET_RATIO` | `0.9` |保留部分 `summary_markdown` |
| `TOOL_RESPONSE_MAX_CHARS` | `40000` |遗留回退，如果 `TOOL_RESULT_MAX_CHARS` 未设置|

### 异步查询存储

|变量|默认值|描述|
|---|---|---|
| `ASYNC_RESULT_PAGE_SIZE` | `200` |异步结果预览页面大小|
| `ASYNC_RESULT_MEMORY_THRESHOLD_BYTES` | `5000000` |将大型异步结果溢出到磁盘|
| `ASYNC_RESULT_DIR` | `.cerebro/query_results` |异步结果存储|

### 研究存储

|变量|默认值|描述|
|---|---|---|
| `CEREBRO_RESEARCH_DIR` | `.cerebro/research_projects` |本地/开发的持久研究项目根；Docker覆盖到 `/data/research_projects` |
| `RESEARCH_PAGE_SIZE_DEFAULT` | `20` |研究列表的默认页面大小|
| `RESEARCH_PAGE_SIZE_MAX` | `100` |研究列表的最大页面大小|

### 报告、追踪和运输

|变量|默认值|描述|
|---|---|---|
| `CEREBRO_REPORT_DIR` |代码回退 `~/.cerebro/reports`，Docker覆盖 `/data/reports` |报表存储|
| `CEREBRO_SAVED_QUERIES_DIR` |工具回退 `~/.cerebro-mcp`，Docker覆盖 `/data/saved-queries` |已保存的SQL代码段|
| `THINKING_LOG_DIR` | `.cerebro/logs` |推理跟踪目录|
| `THINKING_ALWAYS_ON` | `True` |自动捕获工具调用|
| `THINKING_LOG_RETENTION_DAYS` | `30` |痕迹保留|
| `REPORT_BASE_URL` |空|导出报告的URL前缀|
| `MCP_AUTH_TOKEN` |空|除非启用了不安全模式，否则SSE需要|
| `ALLOW_INSECURE_REMOTE_TRANSPORT` | `False` |禁用本地测试的SSE身份验证|
| `FASTMCP_HOST` | `0.0.0.0` |SSE绑定主机|
| `FASTMCP_PORT` | `8000` |SSE绑定端口|

### 安全和审计

|变量|默认值|描述|
|---|---|---|
| `MCP_SECURITY_POLICY_MODE` | `log_only` |安全策略模式；未来： `warn`, `enforce` |
| `MCP_SECURITY_LOG_DIR` | `.cerebro/security_audit` |每日JSONL安全审计日志目录|
| `MCP_EXPECTED_MANIFEST_SHA256` |空|可选清单引脚；空禁用哈希验证|

### 图表和报告门

|变量|默认值|描述|
|---|---|---|
| `ENFORCE_CHART_PRECONDITIONS` | `True` |启用图表/报告门|
| `MIN_MODELS_DETAILED` | `3` |门控制图前需要对模型细节进行探索|
| `MIN_TABLES_VERIFIED` | `1` |门控制图前要验证的表格|
| `MIN_CHARTS_FOR_REPORT` | `3` |创建报告前的最小注册图表|
| `MIN_EXPLORATORY_QUERIES` | `2` |创建报表前的最少先前查询执行次数|
| `REQUIRE_DIMENSIONAL_BREAKDOWN` | `True` |要求在报表流中进行维度细分|
| `REQUIRE_RELATIONAL_CHART` | `True` |要求在报表流中进行关系分析|

使用 `system_status()` 检查实时解析的配置、缓存大小、传输模式和ClickHouse连接。

### 可观测性

Cerebro MCP公开了全面的Prometheus度量和结构化的JSON日志。Grafana仪表板已准备好导入，请访问 `grafana/cerebro-mcp-observability.json`.

仪表板包括9个部分：

1. **概述** --副本、Pod、重启、镜像
1. **HTTP/SSE** --请求率、p95延迟、4xx/5xx错误
1. **MCP内部** --MCP请求/工具调用率、延迟、顶级故障工具
1. **安全审计** --可疑呼叫、高风险工具呼叫、仅应用程序呼叫、报告身份验证拒绝
1. **工具使用详细信息** --按数量、呼叫分布、错误率、p99延迟列出的顶级工具
1. **语义层** --语义状态、注册表统计信息、查询尝试、路由决策、计划器失败
1. **ClickHouse** --查询速率、延迟、错误、返回的行
1. **Pod资源** --CPU、内存、网络、节流、重启
1. **日志** --结构化日志、工具调用、安全审计事件、工件重新加载

Prometheus指标包括：

- `cerebro_http_*`, `cerebro_mcp_*` --HTTP和MCP协议指标
- `cerebro_clickhouse_*` --ClickHouse查询指标
- `cerebro_security_*` --安全审计计数器（高风险呼叫、可疑标记、仅限应用程序的呼叫）
- `cerebro_report_token_auth_total` --报告端点身份验证事件
- `semantic_*` --语义层指标（查询尝试、计划失败、修复、回退、快照年龄）

低基数指标按工具名称、风险类别和传输跟踪工具调用、计划器失败、重试、回退和安全事件。高基数细节（解析指标、SQL哈希、ClickHouse错误文本）保留在结构化日志和推理跟踪中。

看 [docs/observability.md](docs/observability.md) 对于完整的度量目录、Grafana设置和结构化日志事件参考。

______________________________________________________________________

## 安全和护栏

服务器在执行层强制执行以下操作：

- 只读SQL
- 阻止DDL和DML
- 阻塞 `FORMAT`, `SETTINGS`，以及外部阅读器功能，例如 `s3(...)`, `url(...)`, `remote(...)`
- 数据库列表
- 标识符验证
- 强制结果封顶，即使查询已经包含 `LIMIT`
- ClickHouse值的JSON安全规范化
- TLS的尽力而为操作系统信任存储注入
- 自定义工具使用ClickHouse本机参数绑定——不受SQL注入的影响
- 自定义工具SQL模板是经过同行评审的静态模板；LLM仅提供参数值
- 仪表板脚手架工具在写入任何文件之前通过Pydantic验证蓝图
- `verify_numbers` 该工具在数字声明到达用户之前强制执行算术验证
- 工具风险分类：每个工具都被分配了一个风险类别(`read_only`, `server_state_write`, `workspace_write`, `subprocess`, `app_only`)
- 可疑呼叫检测：标记仅应用程序的工具调用、SSE上的工作区写入和未知工具
- 仅附加安全审计日志：每天包含已编辑参数、SHA-256哈希值、风险等级和可疑标志的JSONL文件
- 安全层仅用于观察(`log_only` 模式）--从不阻止工具执行

看 [docs/security.md](docs/security.md) 对于完整的安全架构、风险注册表和审计事件模式。

建议的操作硬化：

- 使用最小权限ClickHouse用户
- 保持 `CLICKHOUSE_VERIFY=True`
- 需要 `MCP_AUTH_TOKEN` 在远程SSE上
- 监视器 `cerebro_security_suspicious_calls_total` 在Grafana中用于异常工具调用

已保存查询提醒：

- `save_query` 用于可重用SQL
- 它不是证据存储
- 当您需要持久的查询证据时，使用研究快照

______________________________________________________________________

## 典型用户请求和操作

### 对于任何非平凡的请求：从调度器开始

get_agent_persona("cerebro_dispatcher")

调度员对意图进行分类，运行 `preflight_analytics_request`，选择专业连锁店，并发出强制 **发货清单**。以下模式从属于该清单。仅在琐碎的转弯（“hi”、“list reports”、“open report 3”）、明确的专家调用（“use `forecasting_analyst` 在验证器计数上”），或者在已经调度的工作流中进行后续操作。

### “X有哪些可用数据？”

用途：

1. `discover_models`
1. `get_model_details` 如有需要
1. `describe_table`

### “给我数字或趋势”

用途：

1. `discover_metrics` 和 `query_metrics` 首先，如果请求清晰地映射到受管度量
1. 否则 `discover_models`
1. `describe_table`
1. `execute_query`

如果语义执行不可用或不受支持，请遵循返回的回退原因并使用原始SQL。

如果结果很大或很慢：

1. `start_query`
1. `get_query_results`

### “给我做个图表”

用途：

- `quick_chart` 对于一次性情节
- `generate_chart` 如果您已经处于报告模式，只需要一个图表

### “给我一份报告”

用途：

1. `discover_models`
1. `describe_table`
1. `execute_query` 用于EDA和支持查询
1. `generate_charts`
1. `generate_report`

### “分几个步骤调查此事”

使用研究工作流程：

1. `start_research_project`
1. 阶段规划和执行
1. 持续取证
1. 验证
1. 同行评审
1. 出版物

### “哪些激励措施/排放推动了TVL（或产量、DAU等）？”

使用MMM工作流。这是一个门控流-- `generate_report` 被封锁，直到 `mmm_causal_reviewer` 回报 `VERDICT: PASS`.

1. `get_agent_persona("mmm_analyst")`
1. 遵循SOP：脊柱填充→ 多重共线性→ 基线→ adstock→ fit → 分解
1. 将DAG合成为标记表
1. `get_agent_persona("mmm_causal_reviewer")` --传递DAG；迭代直到通过
1. `generate_charts` （5张所需图表）→ `generate_report`
1. 可选： `get_agent_persona("mmm_simulator")` ±30%有限度的预算再分配

### “给我写一份高管简报/决策备忘录/利益相关者推介”

当用户明确要求提供故事、叙述、备忘录、简报、推销或推荐工件时，使用说书人工作流程。做 **不** 自动升级标准报告请求。如果范围不明确（“给我一份关于X的报告”），询问用户想要哪种模式。

1. `storyteller_start_session`
1. 采用 `get_agent_persona("storyteller_orchestrator")` 和 `("storyteller_context")`
1. 从用户那里收集受众、所需行动、机制、语气
1. `storyteller_record_context_brief(...)` --拒绝模糊的受众
1. 运行正常的Cerebro发现和EDA以收集证据
1. `storyteller_record_big_idea(sentence, stakes)` --一个陈述句
1. `storyteller_record_storyboard(scenes, narrative_order)` --设置→ 紧张→ 决心
1. 对于每个场景： `storyteller_record_visual_spec(...)` 然后 `generate_charts` 然后附上 `chart_id`
1. `storyteller_record_final_story(title, content_markdown)`
1. `storyteller_run_clarity_checks(checks=[...])` --故障循环
1. `storyteller_record_accessibility_pass(passed, notes)`
1. `storyteller_generate_story_report()`

______________________________________________________________________

## 项目结构

cerebro-mcp/ ├── src/cerebro_mcp/ │ ├── server.py │ ├── bootstrap.py │ ├── config.py │ ├── clickhouse_client.py │ ├── artifact_loader.py │ ├── catalog_loader.py │ ├── tool_models.py │ ├── tool_output.py │ ├── safety.py │ ├── manifest_loader.py │ ├── docs_loader.py │ ├── semantic_loader.py │ ├── semantic_models.py │ ├── semantic_index.py │ ├── semantic_graph.py │ ├── semantic_planner.py │ ├── semantic_sql_compiler.py │ ├── dashboard_models.py │ ├── custom_tool_models.py │ ├── research_models.py │ ├── research_store.py │ ├── research_workflow.py │ ├── storyteller_models.py │ ├── storyteller_state.py │ ├── tools/ │ │ ├── query.py │ │ ├── query_async.py │ │ ├── schema.py │ │ ├── dbt.py │ │ ├── metadata.py │ │ ├── saved_queries.py │ │ ├── visualization.py │ │ ├── research.py │ │ ├── session_state.py │ │ ├── reasoning.py │ │ ├── agents.py │ │ ├── dashboard_builder.py │ │ ├── custom_queries.py │ │ ├── cross_check.py │ │ ├── storyteller.py │ │ ├── semantic.py │ │ ├── mini_apps.py │ │ ├── metric_lab.py │ │ ├── contract_explorer.py │ │ └── rpc.py │ ├── security.py │ ├── mini_app_cache.py │ ├── mini_app_models.py │ ├── prompts/ │ ├── resources/ │ └── static/ ├── custom_tools.yaml ├── docs/ │ ├── MINI_APPS.md │ ├── security.md │ └── observability.md ├── grafana/ │ └── cerebro-mcp-observability.json ├── scripts/ ├── ui/ ├── tests/ ├── Dockerfile ├── Makefile └── .env.example

______________________________________________________________________

## 发展

make build-ui make install make dev pytest -v

有用的本地检查：

python -m compileall src tests cerebro-mcp cerebro-mcp --sse python scripts/sync_clickhouse_skills.py /path/to/local/agent-skills-checkout --ref

MCP检查员示例：

uv run mcp dev src/cerebro_mcp/server.py

### 局部语义测试 `dbt-cerebro`

在远程发布任何工件之前，您可以在本地测试语义MCP功能。

1. 在中构建新的工件 `dbt-cerebro`:

cd /path/to/dbt-cerebro dbt docs generate python scripts/semantic/build_registry.py --validate --target-dir target python scripts/semantic/build_semantic_docs.py --target-dir target

2. 点 `cerebro-mcp` 在本地工件路径上清除远程URL：

SEMANTIC_ENABLED=true DBT_MANIFEST_URL= DBT_CATALOG_URL= SEMANTIC_REGISTRY_URL= SEMANTIC_DOCS_INDEX_URL=

DBT_MANIFEST_PATH=/absolute/path/to/dbt-cerebro/target/manifest.json DBT_CATALOG_PATH=/absolute/path/to/dbt-cerebro/target/catalog.json SEMANTIC_REGISTRY_PATH=/absolute/path/to/dbt-cerebro/target/semantic_registry.json SEMANTIC_DOCS_INDEX_PATH=/absolute/path/to/dbt-cerebro/target/semantic_docs_index.json

3. 启动服务器并验证语义行为：

cerebro-mcp

建议检查：

- `discover_metrics`
- `get_metric_details`
- `explain_metric_query`
- `query_metrics`

运行时行为：

- `SEMANTIC_ENABLED=false`：语义工具和资源未注册
- `SEMANTIC_ENABLED=true` 使用健康的本地工件：语义工具已注册并可执行
- `SEMANTIC_ENABLED=true` 对于过时或不匹配的工件：语义工具仍然可用，但执行返回了优雅的不可用或覆盖差距指导

### 仅批准语义执行

`cerebro-mcp` 现在只将语义执行视为已批准：

- 可以发现并执行批准的指标
- 候选指标在注册表/文档层仍然可见，但不可执行
- 当语义覆盖缺失时，MCP返回一个结构化的语义覆盖缺口，并退回到原始SQL路径，而不是默默地将候选资产混合到执行中

语义资源现在更喜欢由引用的生成的语义页面主体 `semantic_docs_index.json`，仅当页面正文不可用时才使用JSON回退。

______________________________________________________________________

## 依赖项

|包装|用途|
|---|---|
| `mcp[cli]` |FastMCP服务器和MCP协议支持|
| `clickhouse-connect` |ClickHouse客户端|
| `pyarrow` |ClickHouse的箭头获取路径|
| `pydantic-settings` |环境支持的设置|
| `python-dotenv` | `.env` 装载|
| `requests` |manifest/docs HTTP获取|
| `truststore` |操作系统信任存储TLS集成|
| `PyYAML` |仪表板配置和自定义工具定义的YAML解析|

前端堆栈：

- 反应
- ECharts
- 顺风
- `@modelcontextprotocol/ext-apps`

______________________________________________________________________

## 许可证

看 [许可证](LICENSE).