AI导哈

餐厅角色扮演报告查询服务

一个基于MCP协议的服务器，提供AI代理查询餐厅角色扮演任务性能数据的工具，支持自定义SQL查询和模式查看。

  • by JeremyDong22
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 JeremyDong22/roleplay-report-mcp

使用说明

角色扮演餐厅报告（MCP服务器）

状态： ✅ 已实施并投入运营

一个模型上下文协议（MCP）服务器，为AI代理提供工具，以便从Supabase查询餐厅角色扮演任务的性能数据。

概述

这款MCP服务器提供了两款强大的工具，用于分析餐厅每日的57项关键绩效指标（KPI）表现数据：

  1. get_view_schema_and_samples - 返回完整的模式信息和示例数据（动态）
  2. execute_custom_query - 执行带有安全验证的自定义SQL查询

特点/功能

  • 只读访问权限 - 所有查询均验证为仅执行SELECT操作
  • 防止SQL注入 - 自动验证阻止危险操作
  • 灵活查询 - AI可以根据模式编写任何SELECT查询
  • 自动截断 - 回复限制为25,000个字符
  • 行限制 - 可配置的限制（默认100行，最大1000行）
  • 中文列名 - 完全支持对商业友好的中文列名

数据源

服务器查询 roleplay_daily_reports 包含以下内容的物化视图：

  • 304条记录 （2025年8月至10月期间）覆盖4家餐厅
  • 57列 为业务清晰起见，使用中文名称
  • 关键维度餐厅、日期、职务（经理/值班经理/厨师）、时间段（7个时段）
  • 关键指标任务数量、完成率、按时完成率

安装

先决条件

  • Python 3.11或更高版本
  • 使用Supabase的项目 roleplay_daily_reports 查看
  • uv 包管理器（推荐）或 pip
  • ✅ Supabase（一个开源的后端服务平台） execute_sql RPC 函数（已创建）

设置步骤

注： 这台服务器已经完全设置完毕！这些步骤仅供参考。

  1. 虚拟环境 ✅ 已创建

    # Already done: uv venv

  2. 依赖项 ✅ 已安装（46个包）

    # Already done: uv pip install -r requirements.txt

  3. 环境配置 ✅ 已配置

    环境变量是在 .mcp.json：

    {
  "env": {
    "SUPABASE_URL": "https://wdpeoyugsxqnpwwtkqsl.supabase.co",
    "SUPABASE_ANON_KEY": "eyJhbGci..."
  }
}

  4. Supabase RPC 函数 ✅ 已创建

    这个（或“该”） execute_sql(text) 在您的 Supabase 数据库中已创建函数，以支持灵活执行 SQL 查询。

使用方法

运行服务器

✅ 服务器已经配置好，当你启动 Claude Code 时将自动开始运行！

MCP服务器已配置在 .mcp.json （项目根目录）并自动启动：

{
  "mcpServers": {
    "roleplay-reports": {
      "type": "stdio",
      "command": "uv",
      "args": ["--directory", "./roleplay-report-mcp", "run", "server.py"],
      "env": {
        "SUPABASE_URL": "https://wdpeoyugsxqnpwwtkqsl.supabase.co",
        "SUPABASE_ANON_KEY": "eyJhbGci..."
      }
    }
  }
}

验证其是否正在运行：

  1. 重启Claude代码
  2. 在MCP服务器状态中查找“角色扮演报告”
  3. 试着问：“角色扮演日报中包含哪些栏目？”

手动测试（可选）

如果您想手动测试服务器（不建议在正常使用中进行）：

# This will start the server and it will hang waiting for stdin - that's normal!
cd /Users/jeremydong/Desktop/myMCPServer/roleplay-report-mcp
source .venv/bin/activate
python server.py

工具

工具1：获取视图模式和样本数据

返回关于数据结构的完整上下文信息。

目的在编写查询之前，为人工智能提供模式信息。

参数无

退货：

  • 全部57个列定义（中文名称、英文名称、数据类型、描述）
  • 最近5条样本记录
  • 元数据（总行数、日期范围、餐厅列表）
  • SQL使用提示和示例

示例用法 （通过MCP）：

# AI calls this tool first to understand data structure
response = get_view_schema_and_samples()
# Then uses column info to write correct queries

工具2：执行自定义查询

执行自定义SQL查询，并自动进行安全性验证。

目的在数据库视图上运行任何只读查询。

参数：

  • query (字符串，必填项)：SQL SELECT 语句
  • row_limit （整数，可选）：要返回的最大行数（默认：100，最大：1000）

回报：

  • success布尔（逻辑）值
  • query执行了查询（已强制应用 LIMIT）
  • row_count返回的行数
  • execution_time_ms查询持续时间
  • data结果对象数组

示例查询：

-- Today's performance for a specific restaurant
SELECT * FROM roleplay_daily_reports
WHERE "餐厅完整名称" ILIKE '%绵阳%'
  AND "运营日期"::date = CURRENT_DATE;

-- Compare all restaurants yesterday
SELECT "餐厅完整名称", "总体任务完成率", "总体任务准时率"
FROM roleplay_daily_reports
WHERE "运营日期"::date = CURRENT_DATE - 1
ORDER BY "总体任务完成率" DESC;

-- Weekly trend for one restaurant
SELECT "运营日期", "总体任务完成率", "总体任务准时率"
FROM roleplay_daily_reports
WHERE "餐厅完整名称" ILIKE '%绵阳%'
  AND "运营日期"::date >= CURRENT_DATE - 7
ORDER BY "运营日期" DESC;

-- Role performance comparison
SELECT "餐厅完整名称",
       AVG("店长任务完成率") as 店长,
       AVG("值班经理任务完成率") as 值班经理,
       AVG("厨师任务完成率") as 厨师
FROM roleplay_daily_reports
WHERE "运营日期"::date >= CURRENT_DATE - 7
GROUP BY "餐厅完整名称";

安全特性

查询验证

  • **仅选择（SELECT-only）**仅允许SELECT查询
  • 关键词屏蔽INSERT、UPDATE、DELETE、DROP、ALTER、CREATE 等操作被阻止
  • 行限制自动执行（最多1000行）
  • 参数化Supabase 客户端处理参数转义

防止SQL注入

服务器采用多层防护措施：

  1. 执行前查询验证
  2. Supabase 客户端内置的参数化功能
  3. 只读数据库凭据（具有有限权限的服务角色）

最佳实践

  • 使用 service_role 仅在安全环境中使用密钥
  • 永远不要在客户端代码中暴露凭据
  • 定期更换密码
  • 监控查询日志以查找可疑活动

常见查询模式

日报

-- Single restaurant today
SELECT * FROM roleplay_daily_reports
WHERE "餐厅完整名称" ILIKE '%绵阳%'
  AND "运营日期"::date = CURRENT_DATE;

趋势

-- Monthly averages
SELECT DATE_TRUNC('week', "运营日期"::timestamp) as 周,
       AVG("总体任务完成率") as 平均完成率
FROM roleplay_daily_reports
WHERE "运营日期"::date >= CURRENT_DATE - 30
GROUP BY 周
ORDER BY 周 DESC;

警报

-- Restaurants with performance issues
SELECT "餐厅完整名称", "总体任务完成率"
FROM roleplay_daily_reports
WHERE "运营日期"::date = CURRENT_DATE - 1
  AND "总体任务完成率" < 50;

故障排除

服务器无法启动

  • 检查Python版本： python --version （必须是3.11及以上版本）
  • 验证虚拟环境是否已激活
  • 检查所有依赖项是否已安装： pip list

“缺少环境变量”错误

  • 环境变量在 .mcp.json (项目根目录)
  • 验证 SUPABASE_URL 和 SUPABASE_ANON_KEY 被正确设置
  • 修改后重启Claude代码 .mcp.json

“未找到 execute_sql 函数”错误

  • ✅ 此函数已在您的Supabase数据库中创建
  • 如果你看到这个错误，请确认你正在使用正确的Supabase项目
  • 检查 Supabase 控制台 → SQL 编辑器 → 运行： SELECT execute_sql('SELECT 1');

查询未返回任何结果

  • 检查日期格式：使用 "运营日期"::date 用于日期比较
  • 验证中文列名是否带有双引号： "餐厅完整名称"
  • 首先在Supabase SQL编辑器中直接测试查询

“关键字不允许”错误

  • 仅允许执行SELECT查询
  • 移除任何 INSERT、UPDATE、DELETE 等关键字
  • 使用 WHERE， ORDER BY， GROUP BY 用于过滤/排序

发展

项目结构

roleplay-report-mcp/
├── server.py              # Main MCP server implementation (485 lines)
├── requirements.txt       # Python dependencies (46 packages)
├── .env.example          # Environment variable template
├── .env                  # Environment variables (gitignored)
├── .venv/                # Virtual environment (Python 3.12)
├── README.md             # This file - user documentation
└── mcp_design.md         # Architecture & implementation documentation

测试查询

在通过 MCP 使用 SQL 查询之前，您可以直接在 Supabase SQL 编辑器中测试它们：

  1. 前往Supabase仪表板 > SQL编辑器
  2. 在（指定的）地方运行你的查询 roleplay_daily_reports
  3. 验证结果
  4. 使用相同的查询语句通过 execute_custom_query

扩展服务器

添加新工具：

  1. 使用 Pydantic 模型定义输入验证
  2. 实现该工具函数 @mcp.tool() 装饰器
  3. 添加中英文的全面文档字符串
  4. 包含错误处理和响应截断
  5. 使用实际查询进行测试

技术细节

字符限制

回复将自动截断至25,000个字符。如果发生截断：

  • _truncated: true 已添加标志
  • _message 解释了截断的原因
  • 对于列表数据，已移除部分行以符合限制

行限制

  • 默认：100行
  • 最大值：1000行
  • 通过 LIMIT 子句自动执行
  • 如果查询的LIMIT较大，则将其减少到最大值

列名处理

在SQL中，中文列名需要使用双引号：

-- Correct
SELECT "餐厅完整名称", "总体任务完成率" FROM roleplay_daily_reports

-- Incorrect (will error)
SELECT 餐厅完整名称, 总体任务完成率 FROM roleplay_daily_reports

许可证

此项目仅供内部使用。版权所有。

支持

对于问题或疑问：

  1. 查看上面的故障排除部分
  2. 查阅design-plan.md文件以获取详细规格说明
  3. 首先在 Supabase SQL 编辑器中测试查询
  4. 检查 Supabase 日志中的数据库错误

Supabase RPC 函数

这个（或“它”） execute_sql 功能

此服务器需要在Supabase中使用自定义的PostgreSQL函数来执行动态SQL查询：

CREATE OR REPLACE FUNCTION execute_sql(query text)
RETURNS json
LANGUAGE plpgsql
SECURITY DEFINER
AS $$
DECLARE
  result json;
BEGIN
  EXECUTE format('SELECT json_agg(t) FROM (%s) t', query) INTO result;
  RETURN COALESCE(result, '[]'::json);
EXCEPTION
  WHEN OTHERS THEN
    RETURN json_build_object('error', true, 'message', SQLERRM);
END;
$$;

状态： ✅ 已在您的Supabase数据库中创建

它的功能是：

  • 接受任何作为文本字符串的SQL查询
  • 使用 PostgreSQL 执行查询 EXECUTE 声明
  • 返回结果为JSON数组
  • 优雅地处理错误

安全性： MCP服务器在将所有查询发送到此函数之前，会对它们进行验证（仅限SELECT查询、关键字屏蔽、行数限制）。

版本历史

  • 1.0.0 (2025-10-22): ✅ 已全面实施并投入运行
    • 两个核心工具：模式探索和自定义查询
    • 仅读访问，附带安全验证
    • 自动响应截断（限制25,000个字符）
    • 支持中文列名
    • Supabase execute_sql 已创建RPC函数
    • 虚拟环境及依赖项已安装
    • MCP服务器配置完成

相关 MCP