Wiki MCP Analytics

维基分析规范MCP服务器

一个在Wiki中维护分析事件规范的系统，然后将其转换为AI编码工具通过模型上下文协议（MCP）高效查询的格式。

概述

分析规范通常存在于开发人员难以使用的分散文档中，或者存在于项目经理和数据科学家难以维护的技术格式中。该项目弥合了这一差距：非技术利益相关者在熟悉的Wiki markdown表中编写规范，而开发人员则通过AI编码工具获得结构化、可查询的数据。

此项目支持基于Wiki的工作流来管理分析规范：

1. Wiki中的作者 -使用markdown表定义事件、属性、属性组和用户属性
2. 自动构建 -转换Wiki标记→ CSV → JavaScript模块
3. 向Claude提问 -MCP服务器为Claude提供搜索和验证规格的工具

注： 该项目使用GitHub/GitLab wiki约定，其中wiki作为markdown文件存储在单独的git存储库中（例如。， repo.wiki.git).这允许以编程方式克隆和处理wiki内容。

特性

• 基于Wiki的创作 -具有版本控制的人性化标记表
• 财产再利用 -定义属性一次，通过属性组到处引用
• 紧凑的响应 -MCP工具返回结构化JSON，将令牌使用量减少约66%
• 验证支持 -根据规范验证跟踪实施
• 本地执行 -使用Claude Desktop在本地运行，无需云托管

安装

注： GitHub私有仓库wiki需要付费计划。GitLab私有仓库包括免费层的wiki（限制为5个用户）。

用作模板（推荐）

此项目被设计为您自己的分析规范的模板。

GitHub Setup

1. 点击 “使用此模板” → “创建新存储库” 在GitHub上
2. 在本地克隆新存储库并安装依赖项：

   git clone https://github.com/yourusername/your-repo-name.git
   cd your-repo-name
   npm install  # Automatically sets up git hooks

1. 用示例内容设置您的wiki：

- 转到GitHub上存储库的Wiki选项卡 - 创建页面： Events.md, Property-Groups.md, Properties.md, User-Properties.md - 复制此项目的内容 wiki-examples/ 目录

1. 触发构建工作流：

- 首选 行动 tab → “将Wiki转换为规范” → “运行工作流”

1. 提取生成的规格：

   git pull

1. 使用您的AI工具进行配置（请参阅下面的“使用AI编码工具进行配置”）

可选增强功能：

• 通过取消注释中的cron作业来启用自动同步 .github/workflows/transform-wiki.yml
• 添加分支保护规则以获得额外的服务器端保护（赫斯基钩子已经阻止了本地提交）

GitLab Setup

1. 分叉或导入此仓库到GitLab
2. 在本地克隆新存储库并安装依赖项：

   git clone https://gitlab.com/yourusername/your-repo-name.git
   cd your-repo-name
   npm install  # Automatically sets up git hooks

1. 用示例内容设置您的wiki：

- 在GitLab中访问项目的Wiki - 创建页面： Events, Property-Groups, Properties, User-Properties - 复制此项目的内容 wiki-examples/ 目录

1. 启用CI推送权限：

- 首选 设置 → CI/CD → 作业令牌权限 - 在...之下 “其他权限”，启用 “允许Git向存储库推送请求” - 点击 保存更改

1. 触发构建管道：

- 首选 构建 → 管道 → 运行管道

1. 提取生成的规格：

   git pull

1. 使用您的AI工具进行配置（请参阅下面的“使用AI编码工具进行配置”）

可选增强功能：

• 通过取消注释中的计划作业来启用自动同步 .gitlab-ci.yml
• 添加受保护的分支规则以获得额外的服务器端保护（赫斯基钩子已经阻止了本地提交）

要求：

• Node.js 20+
• Git
• GitHub或GitLab帐户（用于CI/CD工作流）

快速测试（使用示例数据）

要在不设置wiki的情况下测试MCP服务器：

# Clone the repository
git clone https://github.com/username/wiki-mcp-analytics.git
cd wiki-mcp-analytics

# Install dependencies
npm install

# Build from example data
npm run build:example

# Start the MCP server
npm start

这使用了 wiki-examples/ 生成测试规范的目录。

用法

从Wiki构建规范

# Run full build pipeline (Wiki markdown → CSV → JavaScript)
npm run build

# Run individual steps
npm run build:csv      # Wiki markdown → CSV only
npm run build:js       # CSV → JavaScript only
npm run build:example  # Use wiki-examples/ for testing

注： 开发人员通常不需要运行构建命令。当wiki发生变化时，CI/CD工作流会自动生成并提交规范。就 git pull 获取最新信息。

启动MCP服务器

npm start

使用AI编码工具进行配置

克劳德代码

claude mcp add wiki-analytics node /path/to/wiki-mcp-analytics/src/mcp-server/index.js

其他MCP兼容工具

添加到MCP配置文件中：

{
  "mcpServers": {
    "wiki-analytics": {
      "command": "node",
      "args": ["/path/to/wiki-mcp-analytics/src/mcp-server/index.js"]
    }
  }
}

Wiki格式

Wiki使用带有表格的标记页面，其中每一行代表一个项目。

事件.md

属性组.md

电子邮件 account_type 计划|

属性.md

事件特定属性。属性组还可以引用User-Properties.md。

用户属性.md

用户属性通过以下方式在用户配置文件上设置 identify() 或 setUserProperties()它们在会话中持续存在，并用于分割（类似于PostHog人属性或Amplitude用户属性）。

• 设置一次：是 -属性只能设置一次（使用 set_once 操作）
• 设置一次：否 -属性可以更新（使用 set 操作）

选择一种方法

此模板支持两种分析架构：

以用户为中心的平台（PostHog、Amplitude、Mixpanel、Segment）

用户身份与事件分开处理。平台会自动将事件与用户配置文件相关联。

// Identify user once - properties persist on profile
analytics.identify(userId, { plan: 'pro', signup_source: 'referral' });

// Track events - only event-specific properties needed
analytics.track('project_created', { project_id: '123', project_template: 'starter' });

对于这种方法：

• 在中定义用户特征 用户属性.md （用户id、电子邮件、计划等）
• 仅供事件参考 设备/会话上下文 和 事件特定属性
• 不需要 user_context 属性组-平台处理身份

独立事件（数据仓库、BigQuery、Snowflake）

每个事件都包含独立可查询性的完整上下文。没有持久的“用户配置文件”-事件是自包含的行。

// Each event includes all context
analytics.track('project_created', {
  user_id: 'abc-123',
  email: 'user@example.com',
  plan: 'pro',
  project_id: '123',
  project_template: 'starter'
});

对于这种方法：

• 在中定义用户属性 用户属性.md （与上述相同）
• 创建 user_context 属性组 引用用户属性
• 包含 user_context 在需要用户上下文的事件中分组

主要惯例：

• 使用 `

` 用于多值单元格中的换行

• 事件属性在properties.md中定义
• 用户属性在User-properties.md中定义
• 属性组可以引用任一文件中的属性

项目结构

wiki-mcp-analytics/
├── src/
│   ├── builder/             # Build pipeline (Wiki → CSV → JS)
│   │   ├── index.js         # Pipeline orchestration
│   │   ├── wiki-to-csv.js   # Parse markdown → CSV
│   │   └── csv-to-javascript.js  # Generate JS modules
│   └── mcp-server/          # MCP server implementation
│       └── index.js
├── specs/                   # Generated specs (committed by CI/CD)
│   ├── csv/                 # CSV format for tools
│   │   ├── .gitkeep
│   │   └── *.csv (generated)
│   └── javascript/          # JS modules for runtime
│       ├── .gitkeep
│       └── */ (generated)
├── .husky/                  # Git hooks (pre-commit protection)
│   └── pre-commit
├── wiki-examples/           # Example wiki content for testing
│   ├── Events.md
│   ├── Property-Groups.md
│   ├── Properties.md
│   └── User-Properties.md
└── package.json

MCP工具

服务器为实现和验证提供了以开发人员为中心的工具：

get_event_implement

扩展所有属性，获取完整的事件规范。

// Returns structured JSON with property groups, constraints, and notes
get_event_implementation("user_registered")

validate_event_payload

根据规范验证跟踪实现。

// Returns errors, warnings, and valid fields
validate_event_payload("user_registered", { user_id: "123", ... })

搜索事件

按条件查找事件。

// Search by name, table, or property usage
search_events({ query: "registration", has_property: "user_id" })

获取_属性_详细信息

获取事件间的属性定义和使用情况。

// Returns type, constraints, description, and where it's used
get_property_details("user_id")

获取事件

在同一流程/表中查找事件。

// Returns related events for funnel analysis
get_related_events("user_registered")

get_user_property_details

获取用户属性定义。

// Returns type, constraints, set_once behavior, and description
get_user_property_details("plan")

搜索_用户_属性

按条件查找用户属性。

// Search by name/description, optionally filter to set_once only
search_user_properties({ query: "activation", set_once: true })

validate_user_properties

验证用户属性有效负载，并检查操作是否与set_once行为匹配。

// Returns errors, warnings (including operation mismatches), and valid fields
validate_user_properties({ operation: "set", payload: { plan: "pro", signup_source: "referral" } })

建筑

Wiki Repo (separate git repository)
    ↓ (sync via CI/CD)
Main Repo: wiki-mcp-analytics
    ↓ (build pipeline)
specs/csv/ + specs/javascript/
    ↓ (read by)
MCP Server (runs locally)
    ↓ (stdio)
Claude Desktop / Claude Code

注： GitHub/GitLab wiki是独立的存储库，具有 .wiki 后缀。此项目从wiki仓库同步并构建规范。

发展

自动化工作流程

当你更新你的wiki时，GitHub Action会自动：

1. 检测wiki更改
2. 构建新的规范（CSV+JavaScript）
3. 将您的回购作为 github-actions[bot]
4. 开发人员获取更新的规格

可选： 通过取消注释中的cron计划来启用每日同步 .github/workflows/transform-wiki.yml

本地开发

# Test the builder with example data (no wiki setup needed)
npm run build:example

# Build from your wiki (requires wiki/ directory cloned locally)
git clone https://github.com/yourname/wiki-mcp-analytics.wiki.git wiki
npm run build

# Run the MCP server
npm start

防止腐败

该项目包括一个预提交钩子（通过Husky），它阻止手动提交到 specs/这确保了只有CI/CD提交生成的规范。

要绕过（不建议）： git commit --no-verify

为了获得额外的保护，考虑制定分支保护规则来限制 specs/ 变化。

许可证

MIT许可证-请参阅 许可证 了解详情。

相关

• 模型上下文协议 -此服务器实现的协议
• 克劳德桌面版 -连接到MCP服务器的AI助手