Semantic Metrics Modeling Assistant

A production-ready MCP agent that helps data teams define, validate, and visualize semantic metrics with enterprise-grade persistence, trust scoring, and BI integrations.

Overview

Semantic Metrics Modeling Assistant 是一个基于 Model Context Protocol (MCP) 的智能体，专为降低数据团队在语义层工作中的认知负荷而设计。它提供用于定义指标的对话式界面、血缘与依赖的可视化反馈，以及带持久化存储的精细化信任指标，帮助团队对数据建立信心。

Related MCP server: RunContext

Key Features

Enterprise Data Persistence

• SQLite Database - 完整审计跟踪的持久化存储

• 5-Table Schema - 指标、历史、测试、使用与信任评分

• Change Tracking - 所有指标修改的完整历史

• Version Control Ready - 为 Git 集成与回滚而设计

💬 Conversational Metric Definition

通过对话自然定义指标：

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

📊 BI Tool Integrations

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

• Looker (LookML) - 生成生产就绪的 LookML 文件

• Tableau (TDS) - 导出为 Tableau 数据源 XML

• dbt - 创建 dbt 指标 YAML 定义

🎯 Enhanced Trust Scoring

基于加权算法的多维度质量评估：

• Tests（权重 35%）- 验证测试覆盖率与通过率

• Usage（权重 20%）- 跨团队与仪表盘的采用度

• Freshness（权重 15%）- 带时间衰减的数据陈旧度

• Documentation（权重 15%）- 完整性与清晰度

• Ownership（权重 15%）- 明确的责任归属

• Trend Analysis - 通过迷你趋势线追踪随时间改变的质量变化

🎨 Visual Lineage & Dependencies

现代可视化选项帮助理解指标之间的关系：

• Mermaid Diagrams - Web 前端友好的高度示图，适合 GitHub/Notion/Confluence

• ASCII Trees - 终端认可的依赖可视化

• Impact Analysis - 变更前了解下游影响

• Circular Dependency Detection - 发现并解决冲突

✅ Comprehensive Testing

生产级测试覆盖：

• 35 + Tests - 数据库、信任评分、导出器与工具的测试

• pytest Framework - 使用 fixtures 的行业标准测试框架

• 90+ Coverage - 核心功能全面验证

• CI/CD Ready - 为持续集成准备的自动化测试

Why This Matters

问题所在

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

• 指标泛滥 - 核心指标指标存在多种互相冲突的定义

• 信任缺失 - 缺少质量信号，导致指标“挑选”和报告口径不一致

• 认知负荷 - 复杂依赖链与血缘关系难以思考与推理

• 治理碎片化 - 归属与验证方式临时化，甚至根本不存在

解决方案

本智能体通过下面机制解决这些问题：

• Mental abstraction - 自然语言界面将 YAML 配置复杂性包裹起来

• Transparency mechanisms - 多维信任评分让质量可见

• 等 Infrastructure - 内置归属、测试和 document 的引导

• For observability - 遍布使用率与数据新鲜度监控

Architecture

┌─────────────────────────────────────────┐
│  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                          │
└─────────────────────────────────────────┘

Quick Start

Installation

# Clone the repository
git clone https://github.com/jkelleman/semantic-metrics-modeling-assistant.git
cd semantic-metrics-modeling-assistant

# Install dependencies
pip install -e .

# Run the MCP server
python -m semantic_metrics.server

# Or run tests
pytest tests/

Database Setup

首次运行时，智能体会自动创建 SQLite 数据库（metrics.db），其中包括：

• 指标定义表

• 变更历史追击

• 验证测试结果

• 使用情况统计

• 信任分演化

Usage Examples

定义一个新指标：

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")

# Returns:
# 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")

# Returns ASCII tree:
# 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")

# Returns:
# ```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 工具：

# Export to Looker
export_to_looker("Active Users")
# Generates: active_users.lkml

# Export to Tableau
export_to_tableau("Active Users")
# Generates: active_users.tds (XML)

# Export to dbt
export_to_dbt("Active Users")
# Generates: active_users.yml

Design Principles

1. 对话优先

以自然语言界面抽象复杂 YAML 配置，降低学习曲线，将对话体验置于语法记忆之上。

2. 展示，而不是描述

优先以可视化表达替代文本描述。用有向无环图（DAG）渲染血缘关系，让依赖一目了然。

3. 透明度决定信任

把质量指标作为一等公民，以多维信任分透明度影响质量可见度，并提供可操作的信号。

4. 渐进式披露

采用信息分层：默认先提供高数汇总，同时保留向下钻取到元数据低层的能力。

5. 默认治理

通过设计让治理自然而然地发生：利用 prompt、验证、必填域，在减少摩擦的同时保证最安全的约束。

Use Cases

数据团队成员

“我需要一个让大家都信赖的客户流转价值指标。”

助手可以：

• 用自然语言定义指标

• 验证 SQL 逻辑

• 检查是否已有类似的指标定义

• 设置归属人、文档

• 把指标添加进目录

分析工程师

“为什么我的 dashboard 与财务口径看到的收入数字不一样？”

助手可以：

• 支持各收入指标的定义

• 展示血缘与数据源

• 找出定义分歧的位置

• 推荐应采播的标准指标（canonical metric）

数据负责人

“哪些指标最核心，且需要补充更好治理？”

助手可以：

• 按使用率与信任分呈现指标

• 找出低使用率高信任度的“高危”指标

• 分析治理覆盖范围

• 跟踪一段时间指标的运行状态

Tech Stack

• Python 3.10+ - 核心语言

• FastMCP - MCP 协议实现

• SQLite - 持久化存储

• pytest - 测试框架＋单元（35+）

• YAML/JSON - 指标定义与导出

• 马文（Mermaid） - 图表生成

MCP 工具（共 13 项）

指标管理

质量 & 信任

（我修正一下：因为原文工具有错误，我保留原文的代码函数名）

工具名：suggest_improvements()

可视化

导出 & 集成

高级主题

This Project Enables

体现：UX 能力

• 认知负载 - 层级抽象：在保留系统保留的同时降低语法复杂度

• 信任得分设计 - 构建可信数据反馈的黑盒透明能力模型

• 渐进式展示 - 展示核心，同时给深入探索的机会

• 对话式界面 - 面向技术命令语言的友好设计

工程能力

• MCP 开发 - 生产用面向任务的智能体，13 个可进工具

• 数据库 - SQLite 持久化，支持多表结构并审计；记录

• 数据模型 - 设计语义层，模型复使用多种定义和还原模式

• 系统架构 - 治理、可观测和自动化的最佳实践

• 测试架构 - pytest 中的 35 项测试——覆盖核心功能

• 与 BI/平台集成 - 即主题导入：到 Looker、Tableau、dbt

• 行业联系 - 数据工程与云和数据治理模式

影响价值评语

作为 Microsoft 的 Principal Content Designer，我在数据与 AI 系统领域进行工作，本项目展示了：

1. 深入了解数据团队的挑战——数据团队在生产环境中面对指标混乱与非信任

2. 面向技术用户的 UX——降低复杂性的方式，而不把系统内部的能量减少

3. 面向设计的透明度——加权的方式提供可信可观测的主要信号

4. 增强的工作流——用 MCP 增强（而不是取代）人类决策与专业

5. 生产级实现——可利用 35+ 测试与数据库库、BI 工具入口实现生产不外挂的风险

所以，这正是企业数据平台需要的“人本中心”的设计：治理无阻、信任易测、复杂度可管理层。

最近更新

✅ SQLite 数据库 - 在多 trans 版本中完整持久化（5 表）
✅ BI 集成 - 新增 Looker 和 Tableau 的导出工具
✅ 增强评估评分 - 带有时间Decay的加权式，提供趋势
✅ Mermaid 图表 - 为文档生成现代图表
✅ 测试套件 - 完全由 pytest 驱动的 35+ 条测试

更多技术细节见IMPLEMENTATION_SUMMARY.md。

关于

Jen Kelleman
Staff 产品设计师

我设计 AI 和数据体验，减少认知负荷，并通过透明、可衡量的体系增强信赖。

连接

• LinkedIn

• Medium

• AI Content Design Handbook

其他计划

其他项目

归档

本 README 属于 Semantic Metrics Modeling Assistant 项目的介绍，其余详见项目仓库源码与文档。

• MCP-Oreilly - 用于内容设计、会议分析和文档编制的三个生产级 MCP 代理

• AI Content Design Handbook - 面向 AI 系统的 UX 写作综合指南

让数据治理以人为本，一次一个指标。