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 分