Wiki MCP Analytics Test

维基分析规范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在本地运行，无需云托管

安装

快速入门（按原样使用）

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

# Install dependencies
npm install

# Start the MCP server
npm start

叉和自定义（推荐）

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

1. 分叉此存储库 到您的帐户
2. 设置您的wiki -将示例wiki中的内容复制到fork的wiki
3. 安装依赖项 -快跑 npm install （自动设置git挂钩）
4. 触发工作流 -转到“操作”选项卡，手动运行“将Wiki转换为规范”
5. 提取生成的规格 -快跑 git pull 获取CI生成的规格
6. 配置MCP -添加到AI工具的MCP配置中（见下文）

可选： 通过取消注释中的cron作业来启用自动同步 .github/workflows/transform-wiki.yml

可选： 添加分支保护规则进行限制 specs/ 仅承诺CI/CD

要求：

• Node.js 20+
• Git

用法

从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_created_at|

属性.md

主要惯例：

• 使用 `

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

• 所有属性都必须在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
└── 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")

建筑

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助手