Wawapp MCP Debug Server

Wawapp MCP调试服务器

使用模型上下文协议（MCP）对WawApp Firebase/Flatter生态系统进行只读调试服务器。

33个生产就绪调试工具 8个专门的套件，用于全面的系统可观测性。

快速开始

先决条件

• Node.js 20+
• Firebase服务帐户 datastore.viewer 和 logging.viewer 角色
• Firebase项目（开发/测试/产品）

安装

# 1. Install dependencies
npm install

# 2. Configure environment
cp .env.example .env
# Edit .env and set ENVIRONMENT=dev

# 3. Add Firebase service account
# Download service account JSON from Firebase Console → Project Settings → Service Accounts
# Save as config/dev-service-account.json

# 4. Build
npm run build

# 5. Run
npm start

______________________________________________________________________

配置

多环境设置

编辑 config/environments.json:

{
  "dev": {
    "projectId": "wawapp-dev",
    "serviceAccountPath": "./config/dev-service-account.json",
    "maxTimeRangeDays": 7,
    "rateLimit": { "perTool": 10, "global": 100 }
  }
}

在中设置活动环境 .env:

ENVIRONMENT=dev

______________________________________________________________________

AI客户端设置（克劳德桌面）

添加到您的Claude Desktop MCP配置中：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json 视窗: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "wawapp-debug": {
      "command": "node",
      "args": [
        "C:\\Users\\hp\\Music\\wawapp-mcp-debug-server\\dist\\index.js"
      ],
      "env": {
        "ENVIRONMENT": "dev"
      }
    }
  }
}

添加此配置后重新启动Claude Desktop。

______________________________________________________________________

可用工具（共33个）

套件1：订单生命周期检查器（4个工具）

wawapp_order_trace -完整订单时间表 跟踪订单的完整生命周期，包括状态转换、驾驶员分配和时间线。

{
  "orderId": "order_abc123",
  "includeNotifications": true
}

wawapp_order_search -搜索和筛选订单 按多个条件搜索订单：状态、司机/客户、价格范围、城市/地区、带分页的时间范围。

{
  "status": "matching",
  "city": "Khartoum",
  "timeRangeMinutes": 1440,
  "limit": 50
}

wawapp_order_anomalies -检测卡住/有问题的订单 主动检测有问题的订单：匹配时间超过10分钟、坐标无效、时间戳缺失、数据不一致。

{
  "timeRangeMinutes": 1440,
  "includeExpired": false,
  "limit": 200
}

wawapp_order_stats -汇总订单统计 全面的订单分析：财务指标、完成率、时间分析、参与度指标。

{
  "timeRangeMinutes": 1440,
  "groupBy": "status"
}

______________________________________________________________________

套件2：驾驶员匹配诊断（5个工具）⭐ 关键的

wawapp_driver_eligibility -检查驾驶员要求 驾驶员订单匹配资格的全面检查：验证状态、个人资料完整性、在线状态、位置有效性。

{
  "driverId": "driver_xyz"
}

wawapp_driver_view_orders -模拟驾驶员的视野 根据驾驶员的当前位置和匹配逻辑，模拟驾驶员应该看到的确切顺序。

{
  "driverId": "driver_xyz",
  "radiusKm": 6.0
}

wawapp_order_visibility -调试为什么订单对驱动程序不可见 通过通过/失败检查，详细诊断特定订单对特定驾驶员不可见的原因。

{
  "orderId": "order_abc123",
  "driverId": "driver_xyz"
}

wawapp_nearby_drivers -查找某个地点附近的司机 通过距离和资格分析，找到一个地点半径范围内的所有司机。

{
  "lat": 15.5007,
  "lng": 32.5599,
  "radiusKm": 10.0,
  "onlineOnly": true,
  "verifiedOnly": true
}

wawapp_matching_performance -匹配算法性能 分析匹配的性能指标：成功率、响应时间、P95指标、驾驶员统计数据。

{
  "timeRangeMinutes": 1440,
  "groupBy": "region"
}

______________________________________________________________________

套件3：数据质量和诊断（3个工具）

wawapp_data_audit -数据一致性验证 验证集合之间的数据完整性：孤立记录、缺少引用、无效数据。

{
  "collection": "orders",
  "checkType": "all",
  "limit": 500
}

wawapp_backend_simulator -模拟后端操作 模拟后端操作以进行测试：订单创建、驱动程序匹配、通知。

{
  "operation": "matchOrder",
  "params": {
    "orderId": "order_abc123"
  }
}

wawapp_log_analyzer -日志分析和模式检测 分析云日志的模式、错误和异常，并按严重程度进行细分。

{
  "timeRangeMinutes": 60,
  "severity": "ERROR",
  "resource": "cloud_function",
  "limit": 100
}

______________________________________________________________________

套件4：实时位置智能（3个工具）

wawapp_driver_location_status -驾驶员位置健康检查 综合位置健康检查：存在、坐标有效、新鲜（\10min Recommendation: Check expireStaleOrders scheduler

______________________________________________________________________

### 套件10：高级诊断（2个工具）

**`wawapp_notification_analytics`** -深度通知传递分析
全面的FCM通知分析：交付率、平台故障、故障原因、多设备检测、每小时时间线和问题用户。

{ "timeRangeMinutes": 1440, "userType": "driver", "notificationType": "new_order" }

**`wawapp_race_condition_detector`** -检测比赛状态
检测并发写入、重复驱动程序分配、冲突状态转换、Firestore事务失败以及同时取消/接受竞争。

{ "timeRangeMinutes": 60, "sensitivityMs": 2000, "orderId": "order_abc123" }

______________________________________________________________________

## 安全与限制

### 只读保证

所有工具都是 **严格只读**。禁止写入、更新或删除。

### 速率限制

- 每个工具每分钟10个请求
- 全球每分钟100个请求
- 可根据环境进行配置

### 时间范围限制

- 默认回溯时间：24小时
- 最大范围：7天（可配置）

### PII屏蔽

- 电话号码：伪装成“+222 3\*\*\*\*\*\*\*”
- 姓名：名字+蒙面姓（“Ahmed M\*\*\*”）
- GPS：四舍五入到小数点后4位（~11m精度）

______________________________________________________________________

## 故障排除

### 错误：“权限被拒绝（Firestore）”

- 检查服务帐户是否已 `roles/datastore.viewer`
- 验证中的服务帐户路径 `environments.json`

### 错误：“超出速率限制”

- 等待速率限制窗口重置
- 增加限制 `environments.json` （不建议用于prod）

### Claude Desktop中未显示任何工具

- 检查MCP配置路径是绝对的（不是相对的）
- 验证 `npm run build` 成功完成
- 重新启动克劳德桌面

______________________________________________________________________

## 发展

Watch mode (auto-rebuild on changes)

npm run dev

Build

npm run build

Lint

npm run lint

______________________________________________________________________

## 项目结构

wawapp-mcp-debug-server/ ├── src/ │ ├── config/ # Environment & collection mappings │ ├── security/ # Rate limiting, PII masking, audit logs │ ├── data-access/ # Firestore & Cloud Logging clients │ ├── server/ # MCP server core │ ├── kits/ # Tool implementations by kit │ ├── utils/ # Haversine, time helpers, error handlers │ └── types/ # TypeScript interfaces ├── context/ # Context files for AI agents ├── config/ # Environment configs & service accounts └── logs/ # Audit logs

______________________________________________________________________

## 许可证

MIT许可证

______________________________________________________________________

## 工具选择指南

根据您的调试场景选择工具：

|症状|推荐工具|
|---------|------------------|
|“司机看不到命令”| `wawapp_driver_eligibility`, `wawapp_driver_view_orders`, `wawapp_driver_location_status` |
|“订单无法匹配”| `wawapp_order_trace`, `wawapp_order_anomalies`, `wawapp_nearby_drivers` |
|“具体订单未显示”| `wawapp_order_visibility`, `wawapp_order_trace` |
|“未收到通知”| `wawapp_fcm_token_status`, `wawapp_notification_delivery_check`, `wawapp_notification_trace` |
|“系统性能问题”| `wawapp_system_health`, `wawapp_performance_trends`, `wawapp_error_rate_monitor` |
|“查找有问题的订单”| `wawapp_order_anomalies`, `wawapp_order_search` |
|“旅行太久了”| `wawapp_trip_route_analyzer`, `wawapp_order_trace` |
|“该地区没有司机”| `wawapp_nearby_drivers`, `wawapp_location_density_heatmap` |
|“云功能未运行”| `wawapp_function_health_check`, `wawapp_scheduler_status`, `wawapp_function_execution_trace` |
|“数据质量问题”| `wawapp_data_audit`, `wawapp_order_anomalies`, `wawapp_error_rate_monitor` |
| **“用户卡在身份验证屏幕上”** | `wawapp_auth_session_check`, `wawapp_auth_flow_audit` |
| **“应用程序无限循环”** | `wawapp_auth_loop_detector`, `wawapp_route_loop_diagnoser` |
| **“用户在屏幕之间跳跃”** | `wawapp_route_loop_diagnoser`, `wawapp_auth_flow_audit` |
| **“PIN无效”** | `wawapp_pin_flow_checker`, `wawapp_auth_session_check` |
| **“多个设备的身份验证问题”** | `wawapp_multi_device_session_audit`, `wawapp_auth_session_check` |
| **“用户卡在入职流程中”** | `wawapp_auth_flow_audit`, `wawapp_auth_session_check` |
| **“AuthGate重建循环”** | `wawapp_auth_loop_detector`, `wawapp_auth_flow_audit` |
| **“需要完整的诊断报告”** | `wawapp_incident_report` （综合一线诊断）|
| **“未知用户问题”** | `wawapp_incident_report` （汇总所有子系统）|
| **“通知未送达用户”** | `wawapp_notification_analytics` |
| **“重复订单/任务”** | `wawapp_race_condition_detector` |
| **“并发更新错误”** | `wawapp_race_condition_detector` |

______________________________________________________________________

## 架构概述

┌─────────────────────────────────────────────────────────────┐ │ AI Client (Claude) │ └──────────────────────┬──────────────────────────────────────┘ │ MCP Protocol ┌──────────────────────▼──────────────────────────────────────┐ │ MCP Debug Server │ │ ┌──────────────────────────────────────────────────────┐ │ │ │ Security Layer (Rate Limiting, PII Masking, Audit) │ │ │ └──────────────────────────────────────────────────────┘ │ │ ┌──────────────────────────────────────────────────────┐ │ │ │ 35 Tools across 10 Kits │ │ │ │ - Order Lifecycle (4) - Location Intelligence (3) │ │ │ │ - Driver Matching (5) - Notifications (4) │ │ │ │ - Data Quality (3) - Cloud Functions (3) │ │ │ │ - System Health (5) - Auth & App Flow (6) │ │ │ │ - Scenario Atoms (int) - Advanced Diagnostics (2) │ │ │ └──────────────────────────────────────────────────────┘ │ └──────────────────────┬──────────────────────────────────────┘ │ Firebase Admin SDK ┌──────────────────────▼──────────────────────────────────────┐ │ Firebase/Firestore (Read-Only) │ │ - orders - driver_locations │ │ - drivers - notifications │ │ - users - Cloud Logging │ └─────────────────────────────────────────────────────────────┘

______________________________________________________________________

## 部署状态

**当前版本**: 1.3.0
**状态**：生产就绪
**工具**：35/35（100%完成）
**套件**: 10
**生成状态**：通过

所有35个调试工具都已实施、测试并准备投入生产使用。

**v1.3.0中的新功能**：Kit 10增加了2个高级诊断工具-- `wawapp_notification_analytics` （深度FCM交付分析）和 `wawapp_race_condition_detector` （并发写入/竞争条件检测）。

**v1.2.0中的新功能**：已添加 `wawapp_incident_report` -一个统一的元工具，聚合来自所有子系统的信号，用于全面的一线诊断。

**v1.1.0版本**：Kit 8添加了6个用于身份验证和应用程序流诊断的工具（无限循环检测、身份验证会话一致性、PIN流验证、多设备冲突）。

有关详细的工具规格，请参阅 `COMPLETE_TOOLSET_PLAN.md`.