Framedash Mcp Server

io.github.crane-valley由 GitHub 账号 crane-valley 发布v0.2.0更新于 Nov 5, 2026

MCP server for Framedash game telemetry: query analytics, heatmaps, perf regressions, and alerts

已验证STDIO仅桌面数据库数据与分析

概览

AI 生成的概览

面向 Framedash 游戏遥测的只读 MCP 服务器，让助手查询分析数据、留存、漏斗、热力图与告警。

可以做什么
  • 对 ClickHouse 事件表执行只读 SQL 查询，可限制返回行数
  • 获取仪表盘 KPI、留存队列、漏斗分析和按维度分组的指标洞察
  • 按引擎世界坐标获取每张地图各格子的热力图数据
  • 列出项目、项目状态、地图、内容注册表条目和告警规则
  • 读取告警触发与恢复历史
适用场景
适合已在 Framedash 中采集游戏遥测数据的团队，希望助手在对话中直接回答玩家活跃、留存、漏斗、地图表现或告警相关问题。
运行要求
以 stdio 在本地运行，通常通过 npm 包用 npx 启动。需要 FRAMEDASH_API_KEY 提供 Framedash API 密钥，原始 query 工具还要求 data:admin 权限。可选 FRAMEDASH_PROJECT_ID 设置默认项目，FRAMEDASH_BASE_URL 可覆盖 API 地址。需要能访问 Framedash API 的网络。
安装前请注意
API 密钥是写入客户端配置的机密；原始 query 工具需要更宽的 data:admin 权限，条件允许时应使用仅含 analytics:read 的密钥。工具虽为只读，但查询会把项目数据发送到 Framedash API，结果也会进入助手对话。

安装

在 SourceWeft 中

  1. 打开 控制台中的 Framedash Mcp Server，将其添加到工作区。
  2. 为需要使用其工具的对话启用该服务。

Desktop only，通过 STDIO。 STDIO 服务会启动本地进程，因此需要 SourceWeft 桌面宿主。

其他 MCP 客户端

参照 仓库 中的启动说明。

README

@framedash/mcp-server

MCP (Model Context Protocol) server for the Framedash game telemetry platform. Provides 12 read-only tools and 4 resources for querying analytics data from LLM-powered tools.

Setup

Claude Desktop

Add to your claude_desktop_config.json:

json
{  "mcpServers": {    "framedash": {      "command": "npx",      "args": ["@framedash/mcp-server"],      "env": {        "FRAMEDASH_API_KEY": "fd_xxx",        "FRAMEDASH_PROJECT_ID": "your-project-uuid"      }    }  }}

VS Code (Claude Extension)

Add to your VS Code settings:

json
{  "claude.mcpServers": {    "framedash": {      "command": "npx",      "args": ["@framedash/mcp-server"],      "env": {        "FRAMEDASH_API_KEY": "fd_xxx",        "FRAMEDASH_PROJECT_ID": "your-project-uuid"      }    }  }}

Environment Variables

VariableRequiredDescription
FRAMEDASH_API_KEYYesAPI key with analytics:read for the aggregate tools; the raw query tool additionally requires data:admin
FRAMEDASH_PROJECT_IDNoDefault project UUID for project-scoped tools
FRAMEDASH_BASE_URLNoAPI base URL (default: https://app.framedash.dev)

If FRAMEDASH_PROJECT_ID is omitted, project-scoped tools still work but require an explicit project_id argument per call.

Tools

ToolDescription
queryExecute SQL analytics query (SELECT only, limit default 100)
get_dashboardProject KPI summary (DAU, MAU, sessions, events)
get_retentionCohort retention data
get_funnelFunnel analysis for event steps
get_insightsEvent insights with grouping
get_heatmapHeatmap grid data for a map
list_projectsShow the project bound to the API key
get_project_statusProject health overview
list_mapsList maps in a project
list_contentList content registry entries
list_alertsList alert rules
get_alert_historyAlert trigger history

Resources

URIDescription
framedash://projectsProject bound to the API key
framedash://projects/{projectId}/mapsMap list with bounds
framedash://projects/{projectId}/contentContent registry
framedash://projects/{projectId}/statusProject health status

Hosted HTTP compatibility

The stateless hosted HTTP endpoint /api/mcp rejects request batches containing more than 100 messages with HTTP 400 and JSON-RPC error code -32600. This limit applies per POST request and is separate from the existing 1 MiB request-body limit. The independent stdio transport remains unaffected.

To accommodate this bound, update clients to split message batches into groups of at most 100 messages, or transmit messages as individual POST requests.

Development

Run from the repository root:

bash
pnpm installpnpm --filter @framedash/mcp-server... buildpnpm --filter @framedash/mcp-server test

With pnpm 9, the trailing ... selects the MCP package plus its workspace dependencies, including @framedash/api-client, before compiling from a clean checkout.

License

MIT

来源：README.md，提交 207298c

工具

12

query

Query Events

Execute a read-only SQL query against the ClickHouse events table. Returns up to `limit` rows (default 100, max 1000).

输入参数sql必填limitproject_id

get_dashboard

Get Dashboard

Get project dashboard metrics (KPIs, daily active users, top events).

输入参数daysproject_id

get_retention

Get Retention

Get player retention cohort analysis.

输入参数daysproject_id

get_funnel

Get Funnel

Analyze event funnels. Requires 2-8 event names as steps.

输入参数dayssteps必填windowproject_id

get_insights

Get Insights

Get aggregated insights for a metric grouped by a dimension.

输入参数dayslimitmetric必填group_by必填event_nameproject_id

get_heatmap

Get Heatmap

Get heatmap grid data for a map. Returns performance metrics per cell in engine world coordinates. For a map whose list_maps upAxis is "y" (Unity, Godot), the ground cell is x/z and y is omitted; otherwise it is x/y.

输入参数daysmap_id必填cell_sizeevent_nameproject_id

list_projects

List Projects

Show the project bound to the current API key.

无需输入参数。

get_project_status

Get Project Status

Get the status of a project (event counts, last event time, etc.).

输入参数project_id

list_maps

List Maps

List all maps in the project.

输入参数project_id

list_content

List Content

List content registry entries (event names, display labels, etc.).

输入参数typeproject_id

list_alerts

List Alerts

List all alert rules in the project.

输入参数project_id

get_alert_history

Get Alert History

Get alert event history (trigger/resolve events).

输入参数limitproject_id

版本历史

3
  1. v0.2.0最新Nov 4, 2026
  2. v0.1.5Sep 25, 2026
  3. v0.1.4Sep 16, 2026

评分

已满足适用检查项的 90%

该评分衡量此收录条目的完整程度，依据注册中心条目、端点与公开来源计算得出。它不是对服务器本身的评价，也不表示服务器安全或当前可用：可连通性是带日期的检查结果，评分也不包含安装量或用户评价。

  • 近 30 天内可连通25 分
  • 已声明认证方式10 分

    请在注册中心条目中声明凭据请求头，或保持端点能够响应探测，以便判定其认证方式。

  • 已列出工具必需15 分
  • 描述必需15 分
  • 图标10 分
  • 文档15 分
  • 许可证10 分