OpenReplay Session Analysis MCP Server

OpenReplay 会话分析 MCP 服务

用于分析 OpenReplay 会话录制和用户行为模式的模型上下文协议（MCP）服务。此服务可让 AI 助手分析用户会话、检测问题，并从 OpenReplay 数据中提供可操作的洞察。

🔥 功能

• 🔍 会话搜索与筛选 - 按日期、用户、错误和时长查找会话
• 📊 用户旅程分析 - 跟踪页面流转和导航模式
• 🐛 问题检测 - 识别愤怒点击、表单放弃和错误
• 🤖 AI 驱动的洞察 - 生成智能会话摘要
• 👥 用户行为分析 - 分析多个会话中的模式
• 🔗 相似会话查找 - 发现存在类似问题的会话

🚀 快速开始

1. 克隆并设置：

   git clone https://github.com/rsp2k/openreplay-mcp-server.git
   cd openreplay-mcp-server
   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   pip install -r requirements.txt
   

2. 配置 OpenReplay 凭据：

   cp .env.example .env
   # Edit .env with your OpenReplay API credentials
   

3. 运行服务：

   python run_server.py
   

⚙️ 配置

在 .env 文件中设置以下环境变量：

OPENREPLAY_API_URL=https://api.openreplay.com
OPENREPLAY_API_KEY=your_api_key_here
OPENREPLAY_PROJECT_ID=your_project_id_here

获取 OpenReplay API 凭据的步骤：

1. 前往 OpenReplay 控制面板
2. 导航至 Settings → API Keys
3. 生成新的 API 密钥
4. 从 URL 或项目设置中复制 Project ID

🛠️ 可用工具

会话管理

• search_sessions - 使用高级筛选条件搜索会话
• get_session_details - 获取详细的会话信息
• get_user_session_history - 查看特定用户的所有会话

分析工具

• analyze_user_journey - 绘制用户导航模式和页面流转
• detect_problem_patterns - 查找愤怒点击、表单问题和错误
• generate_session_summary - 生成 AI 驱动的会话洞察和建议
• find_similar_sessions - 发现相关的异常会话

📋 在 Claude Desktop 中使用

将以下内容添加到 Claude Desktop MCP 配置文件（claude_desktop_config.json）中：

{
  "mcpServers": {
    "openreplay-analysis": {
      "command": "python",
      "args": ["/path/to/openreplay-mcp-server/run_server.py"],
      "env": {
        "OPENREPLAY_API_KEY": "your_api_key_here",
        "OPENREPLAY_PROJECT_ID": "your_project_id_here"
      }
    }
  }
}

💬 示例查询

连接到 Claude Desktop 或其他 MCP 客户端后，你可以询问：

• “查找上周出现错误的会话”
• “分析会话 ABC123 的用户旅程”
• “生成今天异常会话的摘要”
• “显示用户 [email protected] 的所有会话”
• “查找与 XYZ456 类似且发生表单放弃的会话”
• “调试会话 DEF789，并告诉我出了什么问题”

🐳 Docker 用法

用于容器化部署：

# Set environment variables in .env file
docker-compose up

或者手动构建并运行：

docker build -t openreplay-mcp .
docker run -e OPENREPLAY_API_KEY=your_key -e OPENREPLAY_PROJECT_ID=your_project openreplay-mcp

🔧 开发

此服务使用以下技术构建：

• FastMCP - 用于实现服务的官方 Python MCP SDK
• httpx - 用于 OpenReplay API 的异步 HTTP 客户端
• asyncio - 提供 async/await 支持

项目结构

openreplay-mcp-server/
├── openreplay_session_analyzer.py  # OpenReplay client and analysis logic
├── run_server.py                   # FastMCP server with tools
├── mcp.py                          # Django MCP configuration (optional)
├── settings.py                     # Django settings (optional)
├── requirements.txt                # Python dependencies
├── .env.example                    # Environment variables template
├── Dockerfile                      # Container configuration
├── docker-compose.yml              # Docker Compose setup
└── README.md                       # This file

添加新的分析功能

1. 在 openreplay_session_analyzer.py 中的 SessionAnalyzer 类里添加新方法
2. 在 run_server.py 中创建相应的 @mcp.tool() 装饰函数
3. 使用你的 OpenReplay 数据进行测试

📊 会话分析能力

问题检测

• 愤怒点击：多次快速点击，表明用户感到沮丧
• 表单放弃：用户开始填写表单但未完成
• 无效点击：点击了不可交互的元素
• 错误跟踪：JavaScript 错误和异常

旅程分析

• 页面流转映射：跟踪用户在网站中的导航
• 时长分析：了解用户在每个页面上花费的时间
• 跳出率：识别仅访问单个页面的会话
• 操作细分：分析用户交互（点击、滚动、输入）

AI 洞察

• 自动摘要：以自然语言描述会话
• 问题识别：突出显示潜在的 UX 问题
• 性能分析：识别加载缓慢的内容
• 行为模式：识别用户意图和目标

🔗 集成示例

调试工作流

# Search for recent error sessions
sessions = await search_sessions(has_errors=True, start_date="2024-06-01")

# Analyze specific problematic session
summary = await generate_session_summary(session_id="abc123")
problems = await detect_problem_patterns(session_id="abc123")

# Find similar issues
similar = await find_similar_sessions(reference_session_id="abc123", criteria="errors")

UX 研究工作流

# Analyze user behavior over time
user_history = await get_user_session_history(user_id="user123")

# Study navigation patterns
for session in user_sessions:
    journey = await analyze_user_journey(session_id=session.id)
    # Analyze patterns...

📝 API 要求

此服务需要：

• 具有 API 访问权限的 OpenReplay 账户
• 有效的 API 密钥和项目 ID
• 能够访问 OpenReplay API 端点的网络
• Python 3.8+ 环境

🤝 贡献

欢迎贡献！请随时提交 Pull Request。如果要进行重大更改，请先创建 issue，讨论您希望进行的更改。

1. Fork 此仓库
2. 创建您的功能分支（git checkout -b feature/amazing-feature）
3. 提交您的更改（git commit -m 'Add amazing feature'）
4. 将更改推送到分支（git push origin feature/amazing-feature）
5. 创建 Pull Request

📄 许可证

本项目采用 MIT License 授权，详情请参阅 LICENSE 文件。

🙏 致谢

• 感谢 OpenReplay 提供会话回放平台
• 感谢 Model Context Protocol 提供集成框架
• 感谢 FastMCP 提供 Python MCP SDK

📞 支持

如果您遇到问题或有疑问：

1. 查看 Issues 页面
2. 创建新的 issue，并提供详细信息
3. 在现有 issue 中参与讨论

---

为提升用户体验分析而倾力打造 ❤️