JinDaGe - lookerctl MCP Details

article

README

🚀 lookerctl

lookerctl 是一款全面的命令行工具（CLI），用于大规模管理和优化 LookML。它提供了快速验证、本地开发、使用分析等丰富功能，能显著提升工作效率。

🚀 快速开始

# 1. 设置环境
source .env

# 2. 测试连接
lookerctl test

# 3. 导出 LookML
lookerctl export all --output-dir ./lookml

# 4. 执行静态分析和验证（速度快！）
lookerctl validate static ./lookml

# 5. 分析使用情况
lookerctl analyze usage

✨ 主要特性

⚡ 验证速度提升 66 倍：对于大规模的 Looker 实例，本地验证仅需 600 毫秒，而使用 API 则需 40 秒。
🔄 完整的本地开发流程：支持导出 → 编辑 → 验证 → 推送的工作流程。
📊 使用情况分析：帮助了解用户实际使用的字段。
🧪 科学测试：提供 AB 测试和黄金测试，增强信心，补充 Looker 内置的数据测试。
🔍 依赖映射：在进行更改之前了解影响。
🤖 支持 AI：所有输出均为 JSON 格式，便于 AI 消费。
🔌 MCP 服务器：通过模型上下文协议为 AI 代理提供 20 种工具。

📦 安装指南

# 1. 安装依赖项
pip install -r requirements.txt

# 2. 配置凭证（.env 文件）
export LOOKERSDK_BASE_URL=https://your-instance.looker.com:443
export LOOKERSDK_CLIENT_ID=your_client_id
export LOOKERSDK_CLIENT_SECRET=your_client_secret

# 3. 测试连接
lookerctl test

💻 使用示例

基础用法

# 本地开发工作流
# 与本地 git 分支同步
lookerctl session sync my-project

# 导出到本地
lookerctl export project my-project -o ./local

# 进行更改
vim ./local/views/users.view.lkml

# 验证（600 毫秒！）
lookerctl validate static ./local

# 推送到 Looker
lookerctl export push my-project ./local

高级用法

# AB 测试优化
# 在更改前创建基线
lookerctl query-test baseline create model.explore \
  -q query.json -o before.json

# 进行优化更改
# ... 优化 SQL，添加索引 ...

# 更改后进行比较
lookerctl query-test baseline compare model.explore \
  -b before.json

# 结果：✓ 速度提升 39%，且数据无变化！

# 使用情况分析
# 分析正在使用的内容
lookerctl analyze usage -o usage.json

# 查找未使用的探索
lookerctl analyze unused

# 构建依赖图
lookerctl deps build ./lookml -o deps.json

# 为 AI 代理启动 MCP 服务器
# 启动 MCP 服务器（适用于 Claude Desktop）
lookerctl mcp

# 添加到 Claude Desktop 配置：
# {
#   "mcpServers": {
#     "looker": {
#       "command": "/path/to/lookerctl",
#       "args": ["mcp"],
#       "env": { ... }
#     }
#   }
# }

# 然后向 Claude 提问：
# "列出所有 Looker 项目"
# "查找未使用的探索"
# "分析 ./lookml 中的依赖关系"

📚 详细文档

入门指南

入门指南 - 安装和设置
核心概念 - 了解工具

参考文档

CLI 参考 - 完整的命令参考
查询测试 - 基线和 AB 测试
本地验证 - 快速的本地验证
AI 集成 - AI 驱动的工作流
MCP 服务器 - 为 AI 代理集成模型上下文协议

示例

🔧 技术细节

性能表现

| 操作 | API 方法 | 本地图 | 加速比 | |------|----------|--------|--------| | 验证项目 | 40 秒 | 600 毫秒 | 66 倍更快 | | 字段发现 | 2 秒 | 100 毫秒 | 20 倍更快 | | 依赖检查 | 5 秒 | 50 毫秒 | 100 倍更快 |

关键命令

# 会话管理
lookerctl session sync
lookerctl session workspace dev

# 导出/推送
lookerctl export all -o ./lookml
lookerctl export push my-project ./lookml

# 验证
lookerctl validate static ./lookml     # 600 毫秒
lookerctl validate local my-project ./lookml   # 40 秒，准确

# 分析
lookerctl analyze usage
lookerctl deps build ./lookml

# 测试
lookerctl query-test baseline create model.explore -q query.json
lookerctl query-test baseline compare model.explore -b baseline.json
lookerctl query-test golden run

使用场景

开发者

提供类似 Looker 控制台的本地开发工作流。
迭代过程中的快速验证。
使用基线进行安全重构。
更改前的影响分析。

AI 系统

为 AI 代理提供具有 20 种工具的 MCP 服务器。
导出所有 LookML 进行分析。
程序化字段发现。
通过验证进行自动优化。
对改进进行科学测试。

团队

了解用户创建的内容。
通过黄金测试进行 CI/CD 集成。
长期性能跟踪。
自动化优化管道。

支持

📖 文档：请参阅 docs/
🐛 问题反馈：通过团队的问题跟踪器报告
❓ 帮助：从入门指南开始

状态

✅ 可用于生产环境

所有功能均经过端到端测试。
完整的 AB 测试工作流已验证。
本地验证速度提升 66 倍。
提供全面的文档。
完善的错误处理。

版本：0.1.0 最后更新：2025-10-11

完整文档请参阅：docs/README.md

lookerctl