Roleplay Report MCP

MCP数据服务

提供方 JeremyDong22

数据服务 stdio · 本地进程 无需鉴权 社区 / 第三方 Claude
查看接入方式

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

一句话选型结论

按资料字段整理

Roleplay Report MCP 属于数据服务类 MCP 服务器,stdio · 本地进程,无需鉴权,可直接接入 Claude,有可直接执行的安装命令。接入前先确认权限范围;涉及写入、删除或付款的操作,建议先在测试环境验证。

分类数据服务 传输方式stdio · 本地进程 鉴权无需鉴权 部署方式本地部署
GitHub 星标 0 仓库热度,无公开仓库时显示未标注
工具数 未标注 暴露给模型的工具数量
资源 / 提示词 0 / 0 资源与提示词模板数量
维护方 社区 / 第三方 核验等级 仅资料核对

工具与能力

数据服务
数量来自来源目录的标注,具体工具清单以官方文档为准
工具数量未标注暴露给模型可调用的工具个数
资源数量0可读取的资源条目
提示词数量0内置提示词模板数量

能力标签

支持客户端

适用场景

数据分析Python本地部署SQL查询餐厅管理AI工具性能监控

安装与配置

stdio · 本地进程 无需鉴权
客户端在本机拉起子进程,数据不出本机
python server.py

这条命令只是入口,具体启动参数请按官方文档补齐,不要直接照搬到别的服务器。

  1. 1
    准备运行环境

    stdio 服务在本地起进程,需要先装好 Python,再按安装命令拉取依赖。

  2. 2
    安装服务

    复制上面的安装命令执行;命令里带占位符的位置,换成自己的密钥或路径。

  3. 3
    写入客户端配置

    在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,让新配置生效。

  4. 4
    验证是否可用

    连接成功后随便调一个只读工具,确认能返回结果,再接入正式流程。

典型使用场景

3 类
按分类与标签整理的常见用法,具体以官方文档为准
数据库查询

用自然语言查库、取数,不用手写 SQL。

数据同步与清洗

把多来源数据拉到一处做整理。

报表取数

按口径快速拉出统计结果。

选择建议

选之前先看这几条
按条目字段给出的判断,不替你决定用不用

值得选的地方

  • 有现成的安装命令,不用自己找入口,照着跑就能起服务。
  • 已适配 Claude,换客户端不用重新研究配置。
  • 资料标注无需鉴权,装好就能连。

先想清楚的地方

  • stdio 方式要求本地装好运行时(如 Node.js),换机器要重新装一遍。
  • 资料没标注工具数量,实际能力要装好后确认。
  • 版本更新与行为细节以官方仓库为准。

更适合

  • 需要在数据服务场景里让模型直接调用外部能力的人。
  • 已经在用 Claude 的用户,接入路径最短。
  • 想先快速试一下、能接受在本地或自有环境跑服务的人。

不太适合

  • 完全不想在本地装环境的人。
  • 需要厂商级 SLA 和技术支持的生产环境。

同类对比

6 个同类
同分类里挑最接近的几条,字段以各自详情页为准
MCP 服务器工具数传输方式部署方式安装命令最后核验
Roleplay Report MCP当前 未标注 stdio · 本地进程 本地部署 有 2026-05-17
Memory 9d25f64e 9 未标注 未标注 无 2026-05-17
Getzep MCP 9 stdio · 本地进程 本地部署 有 2026-05-17
anything-llm 未标注 stdio · 本地进程 本地部署 有 2026-04-11
Prisma MCP Server 未标注 stdio · 本地进程 本地部署 有 2026-05-17
Astr Bot 未标注 stdio · 本地进程 本地部署 有 2026-05-17

服务器档案

数据服务
字段来自项目仓库与公开索引,中文说明由本站标注
提供方JeremyDong22上游标注的维护方 JeremyDong22
分类数据服务本站按上游分类展示
连接方式stdio · 本地进程客户端在本机拉起子进程,数据不出本机
鉴权方式无需鉴权远程服务建议用最小权限凭据
维护方社区 / 第三方核验等级 仅资料核对
包名 / 运行时未标注 · Python本地安装时用到的包标识与运行时
部署类型本地部署上游给出的部署形态
最近核验2026-05-17上游最后核验时间

详细介绍

10.8 KB
来自项目仓库与上游目录的原文,未做删改

角色扮演餐厅报告(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. 虚拟环境 ✅ 已创建```bash

Already done: uv venv


1. **依赖项** ✅ 已安装(46个包)```bash
# Already done: uv pip install -r requirements.txt
  1. 环境配置 ✅ 已配置

环境变量是在 .mcp.json:```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` (项目根目录)并自动启动:```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. 试着问:“角色扮演日报中包含哪些栏目?”

手动测试(可选)

如果您想手动测试服务器(不建议在正常使用中进行):```bash

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):```python
# 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结果对象数组

示例查询:```sql
-- 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. 执行前查询验证
1. Supabase 客户端内置的参数化功能
1. 只读数据库凭据(具有有限权限的服务角色)

### 最佳实践

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

## 常见查询模式

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

趋势```sql

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


### 警报```sql
-- 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编辑器
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中,中文列名需要使用双引号:```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查询: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服务器配置完成

常见问题

8 问
答案由本站依据条目字段整理,不引用上游原文
Roleplay Report MCP 怎么安装?

在客户端按下面的安装命令接入:python server.py。装完在客户端配置里引用同一个包或端点。

Roleplay Report MCP 怎么在 Claude 里配置?

它的传输方式是stdio · 本地进程,在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,配置才会生效。

Roleplay Report MCP 收费吗?

本站不代收费用,也没有标注具体价格。是否收费取决于服务本身和背后的接口额度,正式使用前按官方说明确认。

Roleplay Report MCP 需要 API Key 吗?

资料标注为无需认证,装好就能连;如果实际调用时报鉴权错误,按官方文档补上凭据。

Roleplay Report MCP 支持哪些客户端?

资料标注支持 Claude;其他客户端只要能配置 MCP Server,也能用同样的命令或地址接入。

Roleplay Report MCP 能提供哪些能力?

资料显示能力标签包括 数据分析、Python、Claude、性能监控。具体工具清单以官方文档为准。

Roleplay Report MCP 需要什么运行环境?

运行时为 Python;属于本地进程,需要在本机装好运行环境。

Roleplay Report MCP 是本地还是远程?

它是本地进程(stdio),由客户端在本机拉起。传输方式为stdio · 本地进程。

热门专题

按标签挑服务器
全部专题 →

服务器信息以作者仓库与官方文档为准;分类、传输方式与鉴权方式的中文说明为中文整理,最近核验 2026-05-17。