Metabase MCP Workshop

代谢酶MCP研讨会

使用AI对编程从头开始为Metabase构建一个功能性的模型上下文协议（MCP）服务器。

🎯 研讨会目标

在这个3小时的实践研讨会结束时，您将：

• ✅ 构建一个完整的MCP服务器，将Claude Code连接到元数据库
• ✅ 通过实施MCP架构来学习
• ✅ 掌握AI编码工具（上下文、技能、代理、计划模式）
• ✅ 在人工智能的帮助下编写经过测试的、类型化的TypeScript代码
• ✅ 部署一个可以立即使用的工作工具

📋 先决条件

• Claude Code、GitHub Copilot CLI或Gemini CLI 安装
• Node.js 20+ 和npm
• Git 用于版本控制
• 代码编辑器 （建议使用VSCode）
• TypeScript基础知识 （适合初学者）
• Docker 桌面版 （用于本地Metabase实例）

🚀 快速开始

# Clone the repository
git clone https://github.com/sfeir/metabase-mcp-workshop
cd metabase-mcp-workshop

# Start Metabase with Docker (includes sample data)
make metabase-up

# Auto-configure Metabase (creates admin user + sample database)
make metabase-setup

# Install dependencies
npm install

# Verify setup
npm run build
# ✅ Should compile without errors

Docker设置：研讨会包括一个完整的Docker Compose环境，其中Metabase和PostgreSQL预先配置了示例数据。这 make metabase-setup 命令会自动使用管理员用户配置Metabase并连接示例数据库。看 详细说明。

📚 厂房结构

第0部分：设置（10分钟）

• 克隆仓库
• 安装依赖项
• 了解MCP和代谢酶

第一部分：背景与基础（25分钟）

练习1：创建CLAUDE.md和脚手架MCP服务器

• 了解为什么上下文很重要
• 定义技术栈和惯例
• 生成MCP服务器结构

第二部分：技能与代理（30分钟）

练习2：提交代码 /commit 技能

• 了解技能与代理人
• 使用常规提交格式

练习3：使用Explore代理探索MCP SDK

• 自主导航代码
• 查找工具定义和模式

第3部分：任务分解（45分钟）

练习4：使用计划模式 executeQuery 工具

• 激活计划模式（Shift+Tab）
• 将工作分解为原子任务
• 编码前验证方法

练习5：逐一执行任务

• 任务1：定义工具模式
• 任务2：创建Metabase API客户端
• 任务3：实施工具处理程序
• 任务4：编写单元测试

第4部分：质量与验证（40分钟）

练习6：强制严格的TypeScript类型

• 配置严格模式
• 添加元数据库API类型
• 消除所有 any 类型

练习7：编写Jest单元测试

• 测试元数据库客户端
• 测试MCP工具
• 模拟外部API

练习8：使用Claude Code进行集成测试

• 构建MCP服务器
• 在Claude代码中配置
• 端到端测试查询

第五部分：调试与恢复（30分钟）

练习9：故意故障和恢复

• 提出一个不可能的请求
• 使用 /clear 重置
• 分解成更小的任务

练习10：与专业代理进行代码审查

• 跑 /git-workflow:code-review
• 修复安全和错误问题
• 验证更正

🛠️ 技术栈

• MCP-SDK: @modelcontextprotocol/sdk -MCP正式实施
• 语言：具有严格模式的TypeScript 5.x
• 运行时：带ESM模块的Node.js 20+
• 测试：Jest用于单元和集成测试
• API客户端：本机获取API
• 运输：stdio（标准输入/标准输出）

📂 项目结构

metabase-mcp-workshop/
├── README.md                    # This file
├── .claude/
│   └── CLAUDE.md                # AI context template
├── src/
│   ├── index.ts                 # MCP server entry point
│   ├── types/
│   │   └── metabase.ts          # Metabase API types
│   ├── tools/
│   │   └── execute-query.ts     # executeQuery tool definition
│   └── client/
│       └── metabase.ts          # Metabase API client
├── test/
│   ├── client/
│   │   └── metabase.test.ts     # Client tests
│   ├── tools/
│   │   └── execute-query.test.ts # Tool tests
│   └── fixtures/
│       └── metabase-responses.json # Mock data
├── docs/
│   └── exercises/
│       ├── 01-context.md        # Exercise 1 guide
│       ├── 02-skills-agents.md  # Exercise 2-3 guide
│       ├── 03-decomposition.md  # Exercise 4-5 guide
│       ├── 04-quality.md        # Exercise 6-8 guide
│       └── 05-debugging.md      # Exercise 9-10 guide
├── package.json                 # Dependencies and scripts
├── tsconfig.json                # TypeScript configuration
└── jest.config.js               # Jest test configuration

🔧 开发命令

MCP服务器命令

# Build the MCP server
npm run build

# Type checking
npm run typecheck

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Lint code
npm run lint

Docker命令

# Start Metabase and PostgreSQL
make metabase-up

# Auto-configure Metabase (admin user + sample database)
make metabase-setup

# Check service status and view credentials
make metabase-status

# View logs
make metabase-logs

# Stop services
make metabase-down

# Reset all data and restart
make metabase-reset

# Open PostgreSQL shell
make metabase-shell

# Show all available commands
make help

看 查看完整的Docker文档。

🎓 你将学到

AI编码原理

1. 上下文优先：创建CLAUDE.md来指导AI
2. 技能与代理：使用专门的工作流程
3. 任务分解：想法→ Spec → Tasks
4. 质量工具：类型、测试、代码审查
5. 恢复策略：AI失败时进行调试

MCP协议

• 具有stdio传输的服务器架构
• 使用JSON模式的工具定义
• 请求/响应处理程序
• 错误处理和日志

API集成

• REST API客户端设计
• 身份验证模式
• 错误处理策略
• 类型安全API调用

🚢 研讨会后的后续步骤

扩展您的MCP服务器

• 添加更多工具： list_databases, create_dashboard, list_tables
• 添加资源：数据库模式、保存的问题
• 实现缓存和流媒体
• 添加webhook通知

部署和共享

• 发布为npm包
• 创建Docker容器
• 提交至MCP市场
• 与社区分享

构建更多MCP服务器

将相同的模式应用于：

• Jira（问题管理）
• Slack（通知）
• GitHub（自动化）
• PostgreSQL（直接数据库访问）
• 谷歌分析（指标）

📖 资源

MCP协议

• 规格
• 培训课程

克劳德代码

• 文档
• 代理技能

元数据库

• API文档

⚡ 快速故障排除

构建失败

# Clear cache and reinstall
rm -rf node_modules package-lock.json
npm install
npm run build

MCP服务器未在Claude代码中启动

• 检查日志： ~/.claude/logs/mcp-server-metabase.log
• 验证中的绝对路径 .claude/settings.json
• 确保 npm run build 成功

克劳德没有看到工具

• 完全重新启动克劳德代码（Cmd+Q/Ctrl+Q）
• 检查工具列在 ListToolsRequest 处理器
• 验证服务器连接（检查日志）

👥 积分

创建于 SFEIR学校 作者：热雷米·普特林

研讨会旨在通过动手MCP实施来教授人工智能辅助开发。

📄 许可证

MIT许可证-可自由使用和修改以用于学习目的