YST KPI Daily Report Collector

Instructions

Implementation Reference

• server.py:46-46 (registration)

  Registers the 'collect_reports' tool using the FastMCP @mcp.tool() decorator.

  @mcp.tool()

• server.py:47-100 (handler)

  Main handler function for 'collect_reports' tool. Performs login verification, optional auto-login, and delegates to ReportCollector for data collection.

  async def collect_reports(start_month: str, end_month: str, output_file: str = None, auto_login: bool = False) -> str:
      """
      采集指定月份范围的日报数据
  
      ⚠️ 重要：使用前请先确保已登录！
  
      推荐流程：
      1. 先调用 check_login_status 检查登录状态
      2. 如果未登录，调用 browser_login 进行登录
      3. 登录成功后，再调用本工具采集数据
  
      这样可以避免采集过程被登录流程阻塞。
  
      Args:
          start_month: 起始月份，格式 YYYY-MM (例如: 2025-07)
          end_month: 结束月份，格式 YYYY-MM (例如: 2025-09)
          output_file: 输出文件路径（可选，默认为 ~/.yst_mcp/output/new.md 或项目目录下 data/new.md）
          auto_login: 未登录时是否自动启动浏览器登录（默认 False，不推荐设为 True）
  
      Returns:
          采集结果描述
      """
      collector = ReportCollector()
      cookie_manager = CookieManager()
  
      try:
          # 检查是否有保存的 Cookie
          if cookie_manager.has_cookies():
              collector.load_saved_cookies()
  
          # 检查登录状态
          if not collector.check_login_status():
              if auto_login:
                  print(safe_text("❌ 未登录，正在启动浏览器..."))
                  # 启动浏览器登录
                  browser_login = BrowserLogin()
                  if await browser_login.launch_persistent_browser():
                      # 重新加载 Cookie
                      collector.load_saved_cookies()
                  else:
                      return safe_text("❌ 登录失败或超时，请重试")
              else:
                  return safe_text(
                      "❌ 未登录或 Cookie 已过期\n\n"
                      "请使用以下方法之一：\n"
                      "1. 调用 browser_login 工具启动浏览器登录\n"
                      "2. 将 auto_login 参数设置为 true，自动打开浏览器"
                  )
  
          # 执行采集
          result = await collector.collect(start_month, end_month, output_file)
          return result
      except Exception as e:
          return f"采集失败: {str(e)}"

• report_collector.py:250-306 (helper)

  Core helper method in ReportCollector class that implements the actual report fetching, month range generation, and Markdown file output generation.

  async def collect(self, start_month: str, end_month: str, output_file: str = None) -> str:
      """
      采集指定月份范围的日报并保存
  
      Args:
          start_month: 起始月份
          end_month: 结束月份
          output_file: 输出文件路径（可选，默认使用自动检测的路径）
  
      Returns:
          采集结果描述
      """
      # 处理输出文件路径
      if output_file is None:
          # 使用默认路径
          output_file = str(self.default_output_dir / 'new.md')
      elif not os.path.isabs(output_file):
          # 如果是相对路径，转换为绝对路径（相对于默认输出目录）
          output_file = str(self.default_output_dir / output_file)
  
      # 确保输出目录存在
      output_path = Path(output_file)
      output_path.parent.mkdir(parents=True, exist_ok=True)
  
      # 加载已保存的 Cookie
      if self.cookie_manager.has_cookies():
          self.load_saved_cookies()
  
      # 检查登录状态
      if not self.check_login_status():
          return safe_text(
              "❌ 未登录或登录已过期\n\n"
              "请先使用以下步骤登录：\n"
              "1. 使用 chrome_devtools_mcp 打开登录页面\n"
              f"2. 访问 {self.LOGIN_URL}\n"
              "3. 手动登录\n"
              "4. 登录成功后，使用 save_cookies 工具保存 Cookie\n"
              "5. 重新调用 collect_reports 工具"
          )
  
      # 生成月份范围
      months = self.generate_month_range(start_month, end_month)
  
      # 采集所有月份的数据
      all_reports = {}
      for month in months:
          print(f"正在采集 {month} 月份日报...")
          reports = self.fetch_month_reports(month)
          all_reports[month] = reports
          print(safe_text(f"  ✓ 采集到 {len(reports)} 条日报"))
  
      # 生成 Markdown 文件
      self._generate_markdown(all_reports, output_file)
  
      total_count = sum(len(reports) for reports in all_reports.values())
      return safe_text(f"✓ 采集完成！共采集 {len(months)} 个月份，{total_count} 条日报，已保存到 {output_file}")