datafinder-mcp

v0.2.1

Published

a month ago

MCP server for Gate DataFinder analytics API

0High
0Medium
0Low

highstarwu

DataFinder-mcp

Gate 私有化 DataFinder 的 Cursor MCP Server（stdio）。封装事件趋势、漏斗转化、看板 DSL 与埋点 registry 查询。

Cursor 里显示名：DataFinder-mcp（mcp.json 的 key，可自定）
npm / npx 包名：datafinder-mcp（npm 仅允许小写）

安全：每人用自己的登录态（必读）

| 变量 | 是否可共享 | 说明 | |------|------------|------| | DATAFINDER_BASE_URL / APP_ID / DASHBOARD_ID | ✅ 可相同 | 平台与看板 ID，非个人密钥 | | DATAFINDER_TRACKING_REGISTRY | ⚠️ 各业务不同 | 本机 tracking-registry.json 绝对路径；MCP 不含业务埋点 | | DATAFINDER_COOKIE | ❌ 禁止共用 | 含 sessionid，绑定你的浏览器登录 | | DATAFINDER_CSRF_TOKEN | ❌ 禁止共用 | 与 Cookie 成对，每人从自己的 F12 复制 |

MCP npm 包只分发程序；绝不在 README、mcp.json.example、技术方案里写真实 Cookie/CSRF。
同事配置：复制 .cursor/mcp.json.example → 本地 .cursor/mcp.json，只填自己的 Cookie/CSRF。
你的 .cursor/mcp.json 已加入 .gitignore，避免误提交 session。

埋点数据来源（二选一，飞书优先）

方式 1：飞书多维表格（推荐 · 一人改全队同步）

默认：手动刷新模式（DATAFINDER_TRACKING_CACHE_TTL_SEC=0 或不配置）

首次 list_tracking_events / query_event 会从飞书或本地 JSON 加载
之后一直用内存缓存，不会按时间自动重拉
飞书表有更新时，调用 refresh_tracking_registry（或 list_tracking_events(force_refresh=true)）

可选：设 DATAFINDER_TRACKING_CACHE_TTL_SEC=3600 等正整数，则 N 秒后自动重拉（旧行为）。

"DATAFINDER_TRACKING_LARK_APP_TOKEN": "GsyVb50tVawNREsonjVjDstPpCh",
"DATAFINDER_TRACKING_LARK_TABLE_ID": "tbljItIka7COtT4K",
"DATAFINDER_TRACKING_LARK_VIEW_ID": "vew9LYkS3B",
"LARK_APP_ID": "<与 lark-mcp 相同>",
"LARK_APP_SECRET": "<与 lark-mcp 相同>"

app_token：wiki 链接里 table= 前的多维表格 token，或对 wiki 节点调 API 得 obj_token
应用需有该表的查看权限（与 lark-mcp 同一应用即可）
首次必做：在飞书开放平台为应用 cli_a9042dd6d2f89e1b 开通权限 bitable:app:readonly（或 base:record:retrieve），并发布版本。否则 tenant token 读表会 Access denied。
表头：event_name, show_name, legacy_name, biz_line, type, key_properties, …

方式 2：本地 JSON / GitLab

"DATAFINDER_TRACKING_REGISTRY": "/path/to/tracking-registry.json"

未配置飞书时回退到本地文件。

新用户要不要本地 JSON？

| 情况 | 要不要 DATAFINDER_TRACKING_REGISTRY | |------|--------------------------------------| | 飞书 Bitable 已开通权限 | 不需要本地文件，只配 DATAFINDER_TRACKING_LARK_* | | 飞书 暂未开通 | 二选一：开通 bitable:app:readonly，或从包内 tracking-registry.example.json 复制到本机并配置路径 | | 飞书 + 想有备份 | 可同时配本地路径；飞书失败时自动回退本地，不崩溃 |

仅飞书、无本地文件：list_tracking_events / refresh 在飞书可用前会返回 setup_required 与分步指引；query_event 仍可直接查（手写 event_name，不依赖 registry）。

发布到 npm 后如何更新版本

cd .cursor/mcp-servers/gate-datafinder
npm run build && npm test
npm version patch   # 0.1.1 → 0.1.2（修 bug）
# 或 npm version minor  # 新功能
npm publish --access public --otp=<6位码>

同事更新 MCP：把 mcp.json 里版本改为新版本号后 Restart DataFinder-mcp。推荐固定版本："args": ["-y", "[email protected]"]。

0.2.1 变更（相对 0.2.0）

默认 event_scope=legacy_merge；2026 仍合并老 App 埋点
auto 与 legacy_merge 全时段按日相加
飞书 Bitable 埋点表 + refresh_tracking_registry；权限未开时 setup_required 指引
飞书失败可回退本地 DATAFINDER_TRACKING_REGISTRY

给别人：npx 一键安装

发布后，对方只需在 Cursor mcp.json（~/.cursor/mcp.json 或项目 .cursor/mcp.json）加入：

{
  "mcpServers": {
    "DataFinder-mcp": {
      "command": "npx",
      "args": ["-y", "datafinder-mcp"],
      "env": {
        "DATAFINDER_BASE_URL": "https://portal.gatedataengine.com",
        "DATAFINDER_APP_ID": "10000001",
        "DATAFINDER_COOKIE": "<自己的 Cookie>",
        "DATAFINDER_CSRF_TOKEN": "<自己的 CSRF>",
        "DATAFINDER_DASHBOARD_ID": "7568800502645793792",
        "DATAFINDER_TRACKING_REGISTRY": "/absolute/path/to/your-team/tracking-registry.json"
      }
    }
  }
}

保存后重启 MCP / 重载 Cursor。npx -y 会自动下载并运行，无需克隆仓库。

每人仍需自己的 Cookie/CSRF（内网登录态），MCP 只分发程序，不分发密钥。

发布到 npm（维护者）

方式 A：公共 npm（对外 / 小团队）

cd .cursor/mcp-servers/gate-datafinder
npm run build
npm login
npm publish --access public

分享指令：npx -y datafinder-mcp（首次会拉包，之后走缓存）。

方式 B：Gate 内部私有源（推荐）

在 package.json 增加 scope，例如 "name": "@gate/datafinder-mcp"。
配置 .npmrc 指向内部 registry（Verdaccio / Artifactory / GitHub Packages）。
npm publish 到内网。
同事 mcp.json 改为：

"args": ["-y", "@gate/datafinder-mcp"]

并在用户或项目 .npmrc 写好 registry 与 token。

方式 C：暂不发布，file: 本地路径

monorepo 或发给同事整个文件夹时：

"command": "node",
"args": ["/path/to/gate-datafinder/dist/index.js"]

对方需自行 npm install && npm run build。

发布前检查清单

| 项 | 说明 | |----|------| | files | package.json 已含 dist、README.md，勿把 Cookie 打进包 | | 版本 | 改 bug 升 patch，npm version patch | | Node | 要求 ≥ 20 | | 试跑 | npx -y datafinder-mcp 本地 npm pack 后 npm i -g ./datafinder-mcp-0.1.0.tgz 验证 |

本地开发配置

"DataFinder-mcp": {
  "command": "node",
  "args": ["/Users/<you>/.../gate-datafinder/dist/index.js"],
  "env": { ... }
}

改代码后：npm run build，重启 MCP。

获取 Cookie / CSRF

打开 DataFinder 事件分析
F12 → Network → analysis POST
复制 Cookie 与 x-csrf-token 到 mcp.json → env

Tools

| Tool | 说明 | |------|------| | check_auth | 鉴权探测 | | query_event | 事件趋势 PV/UV | | get_dashboard / get_report_dsl | 看板与 DSL | | run_report | 看板报表或 steps 漏斗 | | list_tracking_events | 本地 registry |

口径

UV 为日 UV；多日 series 之和 ≠ 周期 DAU。
默认 event_scope=legacy_merge：迁移期新老 App 并行，含 2026 按日相加（老 App 仍有量）。
new_only：仅新 App pay_*；auto 与 legacy_merge 合并行为相同。

安全

含真实 Cookie / CSRF 的 .cursor/mcp.json 勿提交 git（已 .gitignore）。
分享安装说明时只发 mcp.json.example 或 README 片段，不要转发他人填好的 mcp.json。