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

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

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

1. 环境配置 ✅ 已配置

环境变量是在 .mcp.json：

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

1. 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 "总体任务完成率"  SQL编辑器
1. 在（指定的）地方运行你的查询 `roleplay_daily_reports`
1. 验证结果
1. 使用相同的查询语句通过 `execute_custom_query`

### 扩展服务器

添加新工具：

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

## 技术细节

### 字符限制

回复将自动截断至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. 查看上面的故障排除部分
1. 查阅design-plan.md文件以获取详细规格说明
1. 首先在 Supabase SQL 编辑器中测试查询
1. 检查 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服务器配置完成