YST KPI 日报采集 MCP 服务

基于 FastMCP 开发的日报数据自动采集工具，支持从 KPI 系统批量采集指定月份范围的日报数据，并自动生成 Markdown 格式报告。

功能特性

• ✅ 自动登录：使用 Playwright 自动打开浏览器，完成 Google OAuth 登录
• ✅ 持久化会话：登录一次长期有效，会话数据自动保存
• ✅ 批量采集：支持一次性采集多个月份的日报数据
• ✅ 智能检测：自动识别登录状态，7秒检测间隔，不卡顿
• ✅ 格式化输出：自动生成结构化 Markdown 报告
• ✅ 灵活配置：支持自定义输出路径和采集范围

环境要求

• Python: >= 3.10
• 包管理器: uv
• 浏览器: Chromium（Playwright 自动安装）
• 网络: 能访问 https://kpi.drojian.dev

安装配置

1. 安装依赖

cd /Users/admin/go/empty/python/yst_mcp

# 使用 uv 同步依赖
uv sync

# 激活虚拟环境
source .venv/bin/activate

# 安装 Playwright 浏览器
playwright install chromium

2. 配置到 Claude Desktop（MCP 使用）

编辑 Claude Desktop 的 MCP 配置文件：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

添加以下配置：

{
  "mcpServers": {
    "yst-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/Users/admin/go/empty/python/yst_mcp",
        "run",
        "fastmcp",
        "run",
        "server.py"
      ]
    }
  }
}

注意：请将路径 /Users/admin/go/empty/python/yst_mcp 修改为你的实际项目路径。

保存后，重启 Claude Desktop 即可生效。

MCP 使用方法

快速开始

在 Claude Desktop 中直接对话：

使用 yst_mcp 采集 2025-07 到 2025-09 的日报

首次使用会自动打开浏览器，完成 Google 登录后，系统会自动：

1. 提取并保存 Cookie
2. 保存浏览器会话
3. 采集指定月份的日报
4. 生成 Markdown 文件

MCP 工具列表

工具名称	功能说明	是否必需
collect_reports	采集日报（自动登录）	核心工具
browser_login	手动打开浏览器登录	可选
check_login_status	检查登录状态	辅助工具
clear_saved_cookies	清除登录信息	辅助工具
save_cookies_from_browser	手动保存 Cookie（已弃用）	已弃用

使用示例

示例 1：基本采集（推荐）

使用 yst_mcp 采集 2025-04 到 2025-06 的日报

示例 2：自定义输出路径

用 yst_mcp 采集 2025-07 月的日报，保存到 /Users/admin/Downloads/july.md

示例 3：检查登录状态

使用 yst_mcp 检查登录状态

示例 4：清除登录信息

使用 yst_mcp 清除 Cookie

本地调试方法

方法 1：测试脚本（推荐）

项目提供了 test_login.py 测试脚本，用于调试登录功能：

# 激活虚拟环境
source .venv/bin/activate

# 运行测试脚本
python test_login.py

测试脚本会：

1. 启动浏览器
2. 打开登录页面
3. 等待你完成登录
4. 检测登录状态
5. 保存 Cookie 和会话

方法 2：开发模式运行

# 使用 FastMCP 开发模式（带热重载）
uv run fastmcp dev server.py

# 或者生产模式
uv run fastmcp run server.py

方法 3：直接调用函数

# 创建测试文件 test_collect.py
import asyncio
from report_collector import ReportCollector

async def test():
    collector = ReportCollector()
    result = await collector.collect("2025-07", "2025-09", "output.md")
    print(result)

asyncio.run(test())

工具详细说明

1. collect_reports（核心工具）

采集指定月份范围的日报数据。

参数：

• start_month (必需): 起始月份，格式 YYYY-MM，如 2025-07
• end_month (必需): 结束月份，格式 YYYY-MM，如 2025-09
• output_file (可选): 输出文件路径，默认 data/new.md
• auto_login (可选): 是否自动登录，默认 true

返回：采集结果描述（成功/失败信息）

示例：

采集 2025-07 到 2025-09 的日报，保存到 /Users/admin/Downloads/reports.md

2. browser_login

手动打开浏览器进行登录（一般不需要，collect_reports 会自动调用）。

参数：

• use_persistent (可选): 是否使用持久化浏览器，默认 true
• timeout (可选): 登录超时时间（秒），默认 300

返回：登录结果

3. check_login_status

检查当前登录状态，确认 Cookie 是否有效。

参数：无

返回：

• ✓ 已登录，Cookie 有效 - 可以正常采集
• ❌ Cookie 已过期 - 需要重新登录
• ❌ 未找到保存的 Cookie - 首次使用，需要登录

4. clear_saved_cookies

清除保存的登录信息（Cookie 和浏览器会话）。

参数：无

返回：清除结果

注意：清除后需要重新登录！同时会删除：

• data/cookies.json
• data/browser_profile/ 目录（19MB 浏览器会话数据）

5. save_cookies_from_browser（已弃用）

手动保存浏览器 Cookie 字符串。

推荐：直接使用 collect_reports 或 browser_login，无需手动保存 Cookie。

目录结构

python/yst_mcp/
├── server.py              # MCP 服务主入口（5 个工具）
├── browser_login.py       # 浏览器自动登录模块
├── cookie_manager.py      # Cookie 持久化管理
├── report_collector.py    # 日报采集核心逻辑
├── test_login.py          # 登录测试脚本
├── pyproject.toml         # uv 项目配置
├── README.md              # 使用说明（本文件）
├── .venv/                 # 虚拟环境
└── data/
    ├── cookies.json       # Cookie 存储文件（8KB）
    ├── browser_profile/   # 浏览器持久化会话（19MB）
    └── new.md             # 默认输出文件

工作原理

1. 登录流程

graph LR
A[检查登录状态] --> B{Cookie有效?}
B -->|是| F[采集数据]
B -->|否| C[启动浏览器]
C --> D[Google OAuth 登录]
D --> E[保存Cookie和会话]
E --> F

详细步骤：

1. 检查 data/cookies.json 和 data/browser_profile/ 是否存在
2. 如果不存在，启动 Playwright 浏览器
3. 打开 https://kpi.drojian.dev/report/report-daily/my-list
4. 等待用户完成 Google OAuth 登录
5. 每 7 秒检测一次登录状态：
   • URL 包含 kpi.drojian.dev → 已登录
   • URL 包含 my-list → 登录成功
6. 提取 Cookie 并保存到 data/cookies.json
7. 浏览器会话保存到 data/browser_profile/

2. 数据采集流程

遍历月份 → 访问页面 → 解析HTML → 提取数据 → 生成Markdown

详细步骤：

1. 遍历起始月份到结束月份（如 2025-07 到 2025-09）
2. 对每个月份，访问：

   https://kpi.drojian.dev/report/report-daily/my-list?month=YYYY-MM
   

3. 使用 requests + Cookie 获取页面内容
4. 使用 BeautifulSoup 解析 HTML，提取 #report_list li 元素
5. 提取日报信息：
   • 标题（包含日期、时间、早/晚报标记）
   • 内容（今日计划、今日完成等）
6. 按月份组织数据，生成 Markdown 文件

3. 输出格式

# YST 日报整理

生成时间：2025-10-05 10:43:48

## 2025-07 月份日报 (22 条)

### 1. 2025-07-30早报:09:41weather（#郑潇）
当前任务：线上服务开发和测试

今日计划:
1. weather配合继续测试
2. 冷备份数据继续处理
...

---

### 2. 2025-07-29早报:09:12weather（#郑潇）
...

注意事项

安全性

1. ⚠️ Cookie 安全：data/cookies.json 包含登录凭证，请勿分享或提交到 Git
2. ⚠️ 会话数据：data/browser_profile/ 包含完整浏览器会话，请勿分享
3. ✅ 建议：在 .gitignore 中添加：

   data/cookies.json
   data/browser_profile/
   

性能优化

1. 检测间隔：登录检测间隔为 7 秒，避免频繁检查
2. 超时时间：登录超时时间为 5 分钟（300 秒）
3. 持久化会话：首次登录后，浏览器会话自动保存，下次无需重复登录

已知限制

1. 网络依赖：需要稳定的网络连接访问 kpi.drojian.dev
2. 页面结构：依赖页面 HTML 结构（#report_list），如有变化需调整解析逻辑
3. 浏览器依赖：需要 Chromium 浏览器（Playwright 自动管理）

常见问题

Q1: 登录一直卡住不动？

现象：已经登录了，但检测还在等待

原因：登录后停留在其他页面（如 /work/app/index），未跳转到日报页面

解决：最新版本已修复，会自动检测登录状态并跳转到日报页面

Q2: 提示 Cookie 无效？

解决方法：

# 方法 1：使用 MCP 工具
使用 yst_mcp 清除 Cookie
使用 yst_mcp 采集 2025-07 到 2025-09 的日报  # 会自动重新登录

# 方法 2：手动清理
rm -rf data/cookies.json data/browser_profile/

Q3: 浏览器启动失败？

错误信息：Executable doesn't exist at .../chromium-1187/...

解决方法：

# 安装 Playwright 浏览器
source .venv/bin/activate
playwright install chromium

Q4: 网络连接错误？

错误信息：net::ERR_CONNECTION_RESET

解决方法：

• 检查网络连接
• 确认能访问 https://kpi.drojian.dev
• 最新版本已添加错误处理，会自动重试

Q5: 如何完全清除登录信息？

# 清除所有登录数据（Cookie + 浏览器会话）
rm -rf data/cookies.json
rm -rf data/browser_profile/

注意：

• clear_saved_cookies 只清除 cookies.json
• 浏览器会话保存在 browser_profile/（19MB）
• 完全清除需要删除两者

Q6: 可以同时采集多个不同的月份范围吗？

可以，但需要分多次调用。例如：

采集 2025-01 到 2025-03 的日报，保存到 q1.md
采集 2025-04 到 2025-06 的日报，保存到 q2.md

Q7: 输出文件可以放在任意位置吗？

可以！支持绝对路径和相对路径：

# 绝对路径
保存到 /Users/admin/Downloads/report.md

# 相对路径（相对于项目目录）
保存到 reports/2025-07.md

开发者信息

• 项目类型: MCP 服务
• 开发框架: FastMCP
• Python 版本: >= 3.10
• 包管理: uv
• 浏览器自动化: Playwright (async API)
• HTTP 请求: requests + BeautifulSoup4
• 数据格式: Markdown

更新日志

v2.0 (2025-10-05)

• ✅ 使用 Playwright 实现自动登录
• ✅ 持久化浏览器会话
• ✅ 优化登录检测逻辑（7秒间隔）
• ✅ 自动识别已登录状态并跳转
• ✅ 添加错误处理和重试机制

v1.0 (2025-10-02)

• ✅ 基础日报采集功能
• ✅ Cookie 持久化存储
• ✅ Markdown 格式输出

技术支持

如遇问题，请检查：

1. ✅ Python 版本 >= 3.10
2. ✅ 已执行 uv sync 安装依赖
3. ✅ 已执行 playwright install chromium
4. ✅ 网络能访问 https://kpi.drojian.dev
5. ✅ MCP 配置路径正确

更多问题请查看常见问题部分。