shield_lock
JinDaGe
← Back to MCP directory
publicPublicdnsLocal runtime

semantic-metrics-modeling-assistant

一个基于MCP协议的语义指标建模助手，帮助数据团队通过对话式界面定义、验证和可视化业务指标，提供企业级数据持久化、信任评分和BI工具集成功能，减少认知负担并建立数据信任。

article

README

🚀 语义指标建模助手

这是一个可用于生产环境的MCP代理，能帮助数据团队定义、验证和可视化语义指标，具备企业级的数据持久化、信任评分和商业智能（BI）集成功能。

🚀 快速开始

安装

# 克隆仓库
git clone https://github.com/jkelleman/semantic-metrics-modeling-assistant.git
cd semantic-metrics-modeling-assistant

# 安装依赖
pip install -e .

# 运行MCP服务器
python -m semantic_metrics.server

# 或者运行测试
pytest tests/

数据库设置

该代理在首次运行时会自动创建一个SQLite数据库（metrics.db），包含以下内容：

  • 指标定义表
  • 变更历史跟踪
  • 验证测试结果
  • 使用统计信息
  • 信任评分演变

使用示例

基础用法

定义一个新指标：

define_metric(
    name="Active Users",
    description="Daily unique user logins",
    calculation="COUNT(DISTINCT user_id) WHERE login_date = CURRENT_DATE",
    owner="@data-team",
    tags=["engagement", "daily"]
)

高级用法

检查增强信任评分：

check_trust_score("Active Users")

# 返回结果：
# Trust Score: 87/100 ↗️
# Tests: 4 passing (35/35 points) ✅
# Usage: 12 dashboards, 8 users (18/20 points)
# Freshness: Updated 2 hours ago (14/15 points)
# Documentation: Complete with examples (15/15 points)
# Ownership: @data-team (15/15 points)
#
# Trend: ▂▄▆█ (improving over 30 days)
# Recommendations: Add integration tests for edge cases

可视化指标谱系：

visualize_lineage("Revenue per Customer")

# 返回ASCII树结构：
# Revenue per Customer
#   ├── Total Revenue
#   │   ├── Order Amount (raw.orders)
#   │   └── Refunds (raw.refunds)
#   └── Customer Count
#       └── Unique Customers (raw.users)

生成Mermaid图表：

generate_mermaid_diagram("Revenue per Customer")

# 返回结果：
# ```mermaid
# flowchart TD
#     A[Revenue per Customer] --> B[Total Revenue]
#     A --> C[Customer Count]
#     B --> D[Order Amount]
#     B --> E[Refunds]
#     C --> F[Unique Customers]
# ```

导出到BI工具：

# 导出到Looker
export_to_looker("Active Users")
# 生成：active_users.lkml

# 导出到Tableau
export_to_tableau("Active Users")
# 生成：active_users.tds (XML)

# 导出到dbt
export_to_dbt("Active Users")
# 生成：active_users.yml

✨ 主要特性

🗄️ 企业级数据持久化

  • SQLite数据库 - 具备完整审计跟踪的持久化存储
  • 五表架构 - 包含指标、历史记录、测试、使用情况和信任评分
  • 变更跟踪 - 记录所有指标修改的完整历史
  • 支持版本控制 - 专为Git集成和回滚设计

💬 对话式指标定义

通过自然对话定义指标：

"Define 'Active Users' as daily unique logins"
"Create a metric for revenue per customer"
"What's the definition of our churn rate metric?"

📊 BI工具集成

将指标导出到行业标准平台：

  • Looker (LookML) - 生成可用于生产环境的LookML文件
  • Tableau (TDS) - 以Tableau数据源XML格式导出
  • dbt - 创建dbt指标YAML定义

🎯 增强的信任评分

使用加权算法进行复杂的质量评估：

  • 测试（权重35%） - 验证测试覆盖率和通过率
  • 使用情况（权重20%） - 跨团队和仪表板的采用率
  • 数据新鲜度（权重15%） - 考虑时间衰减的数据陈旧度
  • 文档（权重15%） - 完整性和清晰度
  • 所有权（权重15%） - 明确的责任归属
  • 趋势分析 - 通过迷你图跟踪质量随时间的变化

🎨 可视化谱系和依赖关系

提供现代可视化选项，帮助理解指标关系：

  • Mermaid图表 - 适用于GitHub、Notion、Confluence的精美流程图
  • ASCII树 - 适合终端的依赖关系可视化
  • 影响分析 - 在更改前了解下游影响
  • 循环依赖检测 - 识别并解决冲突

✅ 全面测试

具备可用于生产环境的测试覆盖率：

  • 35+项测试 - 涵盖数据库、信任评分、导出器和工具
  • pytest框架 - 使用行业标准的测试框架和测试用例
  • 90%以上覆盖率 - 核心功能经过全面验证
  • 支持CI/CD - 支持持续集成的自动化测试

📚 详细文档

问题所在

数据团队面临系统性挑战：

  • 指标泛滥 - 核心业务指标存在多个相互冲突的定义
  • 信任缺失 - 缺乏质量信号导致指标选择随意和报告不一致
  • 认知负担过重 - 复杂的依赖链和谱系难以理解
  • 治理分散 - 所有权和验证流程不规范或缺失

解决方案

该助手通过以下方式解决这些挑战：

  • 抽象层 - 自然语言界面简化了YAML配置的复杂性
  • 透明度机制 - 多维信任评分使质量可见
  • 治理自动化 - 内置的所有权、测试和文档提示
  • 可观测性工具 - 跟踪使用情况和监控数据新鲜度

🔧 技术细节

架构

┌─────────────────────────────────────────┐
│  Conversational Interface (MCP Tools)   │
├─────────────────────────────────────────┤
│  • define_metric()                      │
│  • validate_metric()                    │
│  • visualize_lineage()                  │
│  • check_trust_score()                  │
│  • search_metrics()                     │
└─────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────┐
│  Metric Repository                      │
├─────────────────────────────────────────┤
│  • Stores metric definitions            │
│  • Tracks lineage and dependencies      │
│  • Collects usage and quality metadata  │
└─────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────┐
│  Data Source Integrations               │
├─────────────────────────────────────────┤
│  • dbt project files                    │
│  • LookML models                        │
│  • YAML metric specs                    │
│  • SQL queries                          │
└─────────────────────────────────────────┘

设计原则

1. 对话优先

通过自然语言界面抽象复杂的YAML配置。优先考虑对话式交互，减少语法记忆的学习成本。

2. 展示而非告知

优先使用可视化表示而非文本描述。将谱系呈现为有向无环图（DAG），使依赖关系一目了然。

3. 通过透明度建立信任

将质量指标作为一等属性展示。多维信任评分提供有关指标可靠性的可操作信号。

4. 渐进式披露

实现信息层次结构，默认显示高级摘要，同时保留深入查看详细元数据的功能。

5. 默认治理

设计界面使治理成为最简单的路径。使用提示、验证和必填字段来强制执行最佳实践，而不增加额外的操作负担。

使用场景

数据团队成员

“我需要创建一个大家都能信任的客户终身价值指标。”

助手帮助：

  • 用通俗易懂的语言定义指标
  • 验证SQL逻辑
  • 检查是否有类似的现有指标
  • 设置所有权和文档
  • 添加到指标目录

分析工程师

“为什么我的仪表板显示的收入数字与财务部门的不同？”

助手帮助：

  • 比较收入指标定义
  • 展示谱系和数据源
  • 确定定义分歧的地方
  • 推荐标准指标

数据负责人

“哪些指标最关键，需要更好的治理？”

助手帮助：

  • 按使用情况和信任评分展示指标
  • 识别高使用、低信任的指标
  • 跟踪治理覆盖范围
  • 随时间监控指标健康状况

技术栈

  • Python 3.10+ - 核心编程语言
  • FastMCP - MCP协议实现
  • SQLite - 持久化数据库存储
  • pytest - 测试框架，包含35+项测试
  • YAML/JSON - 指标定义和导出格式
  • Mermaid - 现代图表生成工具

MCP工具（共13个）

指标管理

| 工具 | 用途 | 返回结果 | |------|---------|---------|
| define_metric() | 创建或更新指标定义 | 确认信息 + 信任评分 | | search_metrics() | 按名称、标签或所有者查找指标 | 匹配指标列表 | | validate_metric() | 检查SQL语法和逻辑 | 验证结果 + 建议 |

质量与信任

| 工具 | 用途 | 返回结果 | |------|---------|---------|
| check_trust_score() | 计算加权质量评分 | 评分明细 + 趋势 + 建议 | | suggest_improvements() | 获取可操作的质量改进建议 | 优先级改进列表 |

可视化

| 工具 | 用途 | 返回结果 | |------|---------|---------|
| visualize_lineage() | 展示ASCII依赖树 | 格式化的树状图 | | generate_mermaid_diagram() | 创建现代流程图 | Mermaid markdown语法 | | compare_metrics() | 并排比较指标 | 突出显示差异 |

导出与集成

| 工具 | 用途 | 返回结果 | |------|---------|---------|
| export_to_looker() | 生成LookML文件 | 可用于生产环境的.lkml文件 | | export_to_tableau() | 创建Tableau数据源 | TDS XML格式文件 | | export_to_dbt() | 生成dbt指标YAML | 与dbt兼容的.yml文件 |

高级功能

| 工具 | 用途 | 返回结果 | |------|---------|---------|
| analyze_impact() | 评估变更的下游影响 | 受影响的仪表板/指标 |

项目展示内容

用户体验技能

  • 降低认知负担 - 设计抽象层，在不牺牲系统功能的前提下简化复杂系统
  • 信任设计 - 通过透明的质量信号和复杂的加权评分算法建立信任
  • 渐进式披露 - 信息架构在可发现性和详细程度之间取得平衡
  • 对话式用户界面 - 用于技术配置的自然语言界面

技术技能

  • MCP开发 - 具备13个工具和1500+行代码的生产级AI代理
  • 数据库设计 - 采用五表架构和完整审计跟踪的SQLite持久化存储
  • 数据建模 - 语义层设计模式和指标定义框架
  • 系统架构 - 治理自动化和可观测性工具
  • 测试 - 使用pytest进行35+项测试，核心功能覆盖率达90%以上
  • 集成模式 - 支持Looker、Tableau和dbt的BI工具导出器

领域专业知识

  • 指标治理 - 建立所有权模型、验证框架和文档标准
  • 数据谱系 - 构建依赖图和进行影响分析
  • 数据可观测性 - 跟踪数据新鲜度、使用时间衰减进行质量监控和使用分析
  • 语义层 - 现代数据栈模式和指标建模最佳实践

项目重要性

作为微软的首席内容设计师，在处理数据和AI系统时，该项目展示了：

  1. 对数据团队挑战的深刻理解 - 在生产环境中直接面对指标泛滥和信任缺失问题的经验
  2. 面向技术用户的用户体验设计 - 设计抽象层，在保留系统功能的同时降低认知负担
  3. 信任和可观测性设计 - 通过透明的质量工具和加权评分应用企业级治理模式
  4. AI增强工作流程 - 利用MCP增强（而非替代）人类决策和领域专业知识
  5. 可用于生产环境的实现 - 35+项测试、数据库持久化和BI集成，可用于实际部署

这代表了企业数据平台所需的以用户为中心的设计：无缝的治理、可衡量的信任和可管理的复杂性。

📄 许可证

本项目采用 MIT许可证。

近期改进

✅ SQLite数据库 - 采用五表架构实现全持久化 ✅ BI集成 - 支持Looker和Tableau导出工具 ✅ 增强的信任评分 - 采用带时间衰减和趋势的加权算法 ✅ Mermaid图表 - 用于文档的现代可视化 ✅ 测试套件 - 使用pytest进行35+项测试，覆盖率达90%以上

完整技术细节请参阅 IMPLEMENTATION_SUMMARY.md。

关于作者

Jen Kelleman
资深产品设计师

我致力于设计AI和数据体验，通过透明、完善的系统降低认知负担并建立信任。

联系方式

其他项目

一次一个指标，让数据治理以用户为中心。

help

Runtime guide

cloud

Hosted runtime

Hosted servers run from a provider-managed environment. You usually connect the MCP client to the hosted endpoint or follow the provider's authorization flow, without keeping a local process alive

  1. Open provider connection page
  2. Authorize or copy endpoint
  3. Connect from your MCP client
terminal

Local runtime / other methods

Local servers run on your own machine or infrastructure. You normally copy the server_config into your MCP client, install the required package, and provide env variables from env_schema when needed

  1. Copy server_config
  2. Install required package
  3. Fill env variables and restart client