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 登录后，系统会自动：
- 提取并保存 Cookie
- 保存浏览器会话
- 采集指定月份的日报
- 生成 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
测试脚本会：
- 启动浏览器
- 打开登录页面
- 等待你完成登录
- 检测登录状态
- 保存 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-07end_month(必需): 结束月份，格式YYYY-MM，如2025-09output_file(可选): 输出文件路径，默认data/new.mdauto_login(可选): 是否自动登录，默认true
返回：采集结果描述（成功/失败信息）
示例：
采集 2025-07 到 2025-09 的日报，保存到 /Users/admin/Downloads/reports.md
2. browser_login
手动打开浏览器进行登录（一般不需要，collect_reports 会自动调用）。
参数：
use_persistent(可选): 是否使用持久化浏览器，默认truetimeout(可选): 登录超时时间（秒），默认300
返回：登录结果
3. check_login_status
检查当前登录状态，确认 Cookie 是否有效。
参数：无
返回：
✓ 已登录，Cookie 有效- 可以正常采集❌ Cookie 已过期- 需要重新登录❌ 未找到保存的 Cookie- 首次使用，需要登录
4. clear_saved_cookies
清除保存的登录信息（Cookie 和浏览器会话）。
参数：无
返回：清除结果
注意：清除后需要重新登录！同时会删除：
data/cookies.jsondata/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
详细步骤：
- 检查
data/cookies.json和data/browser_profile/是否存在 - 如果不存在，启动 Playwright 浏览器
- 打开
https://kpi.drojian.dev/report/report-daily/my-list - 等待用户完成 Google OAuth 登录
- 每 7 秒检测一次登录状态：
- URL 包含
kpi.drojian.dev→ 已登录 - URL 包含
my-list→ 登录成功
- URL 包含
- 提取 Cookie 并保存到
data/cookies.json - 浏览器会话保存到
data/browser_profile/
2. 数据采集流程
遍历月份 → 访问页面 → 解析HTML → 提取数据 → 生成Markdown
详细步骤：
- 遍历起始月份到结束月份（如 2025-07 到 2025-09）
- 对每个月份，访问：
https://kpi.drojian.dev/report/report-daily/my-list?month=YYYY-MM - 使用 requests + Cookie 获取页面内容
- 使用 BeautifulSoup 解析 HTML，提取
#report_list li元素 - 提取日报信息：
- 标题（包含日期、时间、早/晚报标记）
- 内容（今日计划、今日完成等）
- 按月份组织数据，生成 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（#郑潇）
...
注意事项
安全性
- ⚠️ Cookie 安全：
data/cookies.json包含登录凭证，请勿分享或提交到 Git - ⚠️ 会话数据：
data/browser_profile/包含完整浏览器会话，请勿分享 - ✅ 建议：在
.gitignore中添加：data/cookies.json data/browser_profile/
性能优化
- 检测间隔：登录检测间隔为 7 秒，避免频繁检查
- 超时时间：登录超时时间为 5 分钟（300 秒）
- 持久化会话：首次登录后，浏览器会话自动保存，下次无需重复登录
已知限制
- 网络依赖：需要稳定的网络连接访问
kpi.drojian.dev - 页面结构：依赖页面 HTML 结构（
#report_list），如有变化需调整解析逻辑 - 浏览器依赖：需要 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 格式输出
技术支持
如遇问题，请检查：
- ✅ Python 版本 >= 3.10
- ✅ 已执行
uv sync安装依赖 - ✅ 已执行
playwright install chromium - ✅ 网络能访问
https://kpi.drojian.dev - ✅ MCP 配置路径正确
更多问题请查看常见问题部分。