使用说明

维基分析规范MCP服务器

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

概述

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

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

Wiki中的作者 -使用markdown表定义事件、属性、属性组和用户属性
自动构建 -转换Wiki标记→ CSV → JavaScript模块
向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

点击 “使用此模板” → “创建新存储库” 在GitHub上

在本地克隆新存储库并安装依赖项：

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

用示例内容设置您的wiki：
- 转到GitHub上存储库的Wiki选项卡
- 创建页面： Events.md, Property-Groups.md, Properties.md, User-Properties.md
- 复制此项目的内容 wiki-examples/ 目录
触发构建工作流：
- 首选行动 tab → “将Wiki转换为规范” → “运行工作流”
提取生成的规格：
```
git pull
```
使用您的AI工具进行配置（请参阅下面的“使用AI编码工具进行配置”）

可选增强功能：

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

GitLab Setup

分叉或导入此仓库到GitLab

在本地克隆新存储库并安装依赖项：

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

用示例内容设置您的wiki：
- 在GitLab中访问项目的Wiki
- 创建页面： Events, Property-Groups, Properties, User-Properties
- 复制此项目的内容 wiki-examples/ 目录
启用CI推送权限：
- 首选设置 → CI/CD → 作业令牌权限
- 在...之下 “其他权限”，启用 “允许Git向存储库推送请求”
- 点击 保存更改
触发构建管道：
- 首选构建 → 管道 → 运行管道
提取生成的规格：
```
git pull
```
使用您的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

事件名称	事件描述	属性组	其他属性	注释
user_register_collect	用户已完成注册	user_context 设备信息	注册方法 referral_code_used	注册成功后触发

属性组.md

组名称	描述	属性
user_context	用户标识属性（引用user properties.md）	user_id 电子邮件 account_type 计划

属性.md

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

属性名称	类型	约束	描述	用法
device_type	string	枚举：移动设备、平板电脑、台式机	设备类型	包含在device_info组中

用户属性.md

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

属性名称	类型	约束	设置一次	描述
user_id	string	正则表达式：^[0-9a-f-]{36}$	yes	用户的唯一标识符。用于identify（）调用。
plan	string	枚举：免费、专业、企业	否	当前订阅层。按计划细分。
signup_source	string	enum：自然、推荐、付费	是	用户是如何发现产品的。归因分析。

设置一次：是 -属性只能设置一次（使用 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 在需要用户上下文的事件中分组

主要惯例：

使用 <br> 用于多值单元格中的换行
事件属性在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会自动：

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

可选： 通过取消注释中的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许可证-请参阅许可证了解详情。