使用说明

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 -驾驶员位置健康检查综合位置健康检查：存在、坐标有效、新鲜（<5min）、准确（<50m）。

{
  "driverId": "driver_xyz"
}

wawapp_location_density_heatmap -地理分布分析通过供需比计算，按地区分析驱动因素和订单密度。

{
  "region": "Khartoum",
  "radiusKm": 20.0,
  "includeOrders": true,
  "includeDrivers": true
}

wawapp_trip_route_analyzer -分析已完成的行程路线分析行程路线是否异常：距离比较、持续时间分析、绕行检测。

{
  "orderId": "order_abc123"
}

工具包5：通知传递跟踪器（4个工具）

wawapp_fcm_token_status -FCM令牌健康检查检查用户的FCM令牌有效性和健康状态。

{
  "userId": "user_xyz",
  "userType": "driver"
}

wawapp_notification_trace -订单通知时间表跟踪订单发送的所有通知，包括交货状态和时间。

{
  "orderId": "order_abc123"
}

wawapp_notification_delivery_check -全面的交付诊断完整的通知传递检查：令牌有效性、权限、设备状态、最近的传递。

{
  "userId": "user_xyz",
  "userType": "driver"
}

wawapp_notification_batch_check -批量通知健康检查使用聚合统计信息扫描多个用户的通知运行状况。

{
  "userType": "drivers",
  "limit": 100,
  "onlineOnly": true
}

套件6：云功能执行观察者（3个工具）

wawapp_function_execution_trace -功能执行分析使用时间、错误和性能指标跟踪云函数执行。

{
  "functionName": "expireStaleOrders",
  "timeRangeMinutes": 60,
  "includeErrors": true
}

wawapp_function_health_check -全系统功能健康状况对所有云功能进行健康检查，包括执行率和错误率。

{
  "timeRangeMinutes": 60
}

wawapp_scheduler_status -云计划程序作业状态使用从系统行为推断的运行状况检查计划作业的状态。

{
  "jobName": "expireStaleOrders"
}

套件7：系统健康仪表板（5个工具）

wawapp_system_health -全面的系统概述全系统健康检查：订单、驱动程序、客户、具有健康状态的绩效指标。

{
  "timeRangeMinutes": 60
}

wawapp_active_users -主动用户跟踪使用参与度指标跟踪活跃用户（驾驶员和客户）。

{
  "timeRangeMinutes": 60,
  "userType": "all"
}

wawapp_performance_trends -历史业绩分析通过周期比较和趋势检测分析随时间变化的性能趋势。

{
  "timeRangeMinutes": 1440,
  "compareWithPrevious": true
}

wawapp_error_rate_monitor -全系统错误检测监控系统范围内的错误，包括严重性分类和运行状况。

{
  "timeRangeMinutes": 60,
  "limit": 200
}

wawapp_incident_report -统一的事件诊断全面的跨系统诊断，汇总来自身份验证、应用程序流、位置、匹配、通知的信号，以提供优先的根本原因分析。

{
  "uid": "driver_abc123",
  "orderId": "order_xyz789",
  "timeRangeMinutes": 1440,
  "includeDeepDiagnostics": true
}

套件8：身份验证和应用程序流诊断（6个工具）

wawapp_auth_session_check -身份验证会话健康检查检查Firebase auth、自定义声明和Firestore文档之间的身份验证会话一致性。

{
  "uid": "driver_abc123",
  "includeDetails": true
}

wawapp_auth_flow_audit -授权流程时间线审核构建身份验证流程事件的时间线：OTP、PIN、配置文件创建、入职完成。

{
  "uid": "driver_abc123",
  "timeRangeMinutes": 1440,
  "limit": 200
}

wawapp_auth_loop_detector -检测与身份验证相关的无限循环从日志中检测AuthGate重建循环、PIN循环和其他与身份验证相关的无限循环。

{
  "timeRangeMinutes": 60,
  "uid": "driver_abc123",
  "minRepetitions": 100
}

wawapp_route_loop_diagnoser -导航/路线环路检测检测附近的导航环路→ 入职→ 附近的导航日志。

{
  "uid": "driver_abc123",
  "timeRangeMinutes": 120,
  "maxSequenceLength": 50
}

wawapp_pin_flow_checker -PIN流状态验证审核PIN流状态：检查hasPin、pinHash、pinSalt的一致性和最近的尝试次数。

{
  "uid": "driver_abc123",
  "includeAttempts": true
}

wawapp_multi_device_session_audit -多设备会话冲突检查多设备会话问题和设备间的冲突状态。

{
  "uid": "driver_abc123",
  "timeRangeMinutes": 1440
}

示例用法

示例1：“为什么司机看不到订单？”

用户提示AI:

Driver with ID "driver_abc123" complains they can't see any nearby orders.
Can you diagnose why?

AI将使用:

wawapp_driver_eligibility → 检查所有要求
wawapp_driver_view_orders → 显示驾驶员应该看到什么
wawapp_driver_location_status → 检查位置健康状况

期望输出:

The driver cannot see orders because:
- isVerified: false (driver not verified by admin)
- Profile incomplete: missing "city" and "region"
- Location: stale (last updated 15 minutes ago)

Action required:
1. Admin must set isVerified=true in /drivers/driver_abc123
2. Driver must complete onboarding (add city and region)
3. Driver should restart app to refresh location

示例2：“跟踪订单生命周期”

用户提示AI:

Show me the complete timeline for order abc123

AI将使用:

wawapp_order_trace → 获取完整的时间线

期望输出:

Order abc123 Timeline:
1. [10:30:00] Order created (status: matching)
2. [10:32:15] Driver assigned (driver_yyy, status: accepted)
3. [10:35:00] Driver en route (status: onRoute)
4. [11:15:00] Trip completed (status: completed, rating: 5)

Duration:
- Total: 45m 0s
- matchingToAccepted: 2m 15s
- acceptedToCompleted: 42m 45s

示例3：“为什么司机看不到特定的订单？”

用户提示AI:

Order xyz789 is in matching status but driver abc123 can't see it. Why?

AI将使用:

wawapp_order_visibility → 详细诊断

期望输出:

Order xyz789 visibility check for driver abc123:

✓ Order exists and status is "matching"
✓ Driver is verified
✓ Driver profile is complete
✗ Driver is OFFLINE (last seen 2 hours ago)
✗ Distance: 12.3 km (exceeds 6 km radius)

Root cause: Driver is offline and too far from pickup location.

Recommendations:
1. Driver must go online
2. Driver should move closer to Khartoum central area

示例4：“查找卡住的订单”

用户提示AI:

Find all orders that might be stuck or have problems

AI将使用:

wawapp_order_anomalies → 检测有问题的订单

期望输出:

Found 5 anomalies in last 24 hours:

CRITICAL (3):
- Order abc123: Stuck in matching for 25 minutes
- Order def456: Invalid pickup coordinates (0, 0)
- Order ghi789: Missing createdAt timestamp

WARNING (2):
- Order jkl012: Completed but missing completedAt
- Order mno345: Invalid price (0 SDG)

Recommendations:
- Check expireStaleOrders Cloud Function
- Add validation in order creation flow

示例5：“系统健康检查”

用户提示AI:

Give me a comprehensive system health report

AI将使用:

wawapp_system_health → 总体健康指标
wawapp_error_rate_monitor → 错误检测
wawapp_performance_trends → 性能分析

期望输出:

System Health Report (Last 1 hour):

Overall Status: HEALTHY

Orders:
- Total: 247 (↑ 12% vs previous hour)
- Active: 18
- Completed: 215 (87% completion rate)
- Expired: 14

Drivers:
- Total: 156
- Online: 45 (29%)
- Verified: 142 (91%)

Performance:
- Avg matching time: 3.2 minutes (↓ 8% - improving)
- Avg trip duration: 22 minutes
- Rating rate: 78%

Error Rate: 2.4% (5 critical errors detected)

Top Issue: 3 orders stuck in matching >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.

使用说明

Wawapp MCP调试服务器

快速开始

先决条件

安装

配置

多环境设置

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

可用工具（共33个）

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

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

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

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

工具包5：通知传递跟踪器（4个工具）

套件6：云功能执行观察者（3个工具）

套件7：系统健康仪表板（5个工具）

套件8：身份验证和应用程序流诊断（6个工具）

示例用法

示例1：“为什么司机看不到订单？”

示例2：“跟踪订单生命周期”

示例3：“为什么司机看不到特定的订单？”

示例4：“查找卡住的订单”

示例5：“系统健康检查”

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

安全与限制

只读保证

速率限制

时间范围限制

PII屏蔽

故障排除

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

错误：“超出速率限制”

Claude Desktop中未显示任何工具

发展

项目结构

许可证

工具选择指南

架构概述

部署状态

相关 MCP

代码运行服务

React Native调试器MCP

移动开发自动化工具

VS Code模型上下文协议服务器

Dart/Flutter包管理服务器

日志管理服务