YST KPI 日报采集 MCP 服务
基于 FastMCP 开发的日报数据自动采集工具,支持从 KPI 系统批量采集指定月份范围的日报数据,并自动生成 Markdown 格式报告。
功能特性
- ✅ 自动登录:使用 Playwright 自动打开浏览器,完成 Google OAuth 登录
- ✅ 持久化会话:登录一次长期有效,会话数据自动保存
- ✅ 批量采集:支持一次性采集多个月份的日报数据
- ✅ 智能检测:自动识别登录状态,7秒检测间隔,不卡顿
- ✅ 格式化输出:自动生成结构化 Markdown 报告
- ✅ 灵活配置:支持自定义输出路径和采集范围
环境要求
- Python: >= 3.10
- 包管理器: uv
- 浏览器: Chromium(Playwright 自动安装)
- 网络: 能访问
https://kpi.drojian.dev
安装配置
1. 安装依赖```bash
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`
添加以下配置:```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` 测试脚本,用于调试登录功能:```bash
# 激活虚拟环境
source .venv/bin/activate
# 运行测试脚本
python test_login.py
测试脚本会:
1. 启动浏览器
2. 打开登录页面
3. 等待你完成登录
4. 检测登录状态
5. 保存 Cookie 和会话
方法 2:开发模式运行```bash
使用 FastMCP 开发模式(带热重载)
uv run fastmcp dev server.py
或者生产模式
uv run fastmcp run server.py
### 方法 3:直接调用函数```python
# 创建测试文件 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. 登录流程```mermaid
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. 输出格式```markdown
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 无效?
**解决方法**:```bash
# 方法 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/...
解决方法:```bash
安装 Playwright 浏览器
source .venv/bin/activate
playwright install chromium
### Q4: 网络连接错误?
**错误信息**:`net::ERR_CONNECTION_RESET`
**解决方法**:
- 检查网络连接
- 确认能访问 `https://kpi.drojian.dev`
- 最新版本已添加错误处理,会自动重试
### Q5: 如何完全清除登录信息?```bash
# 清除所有登录数据(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 配置路径正确
更多问题请查看常见问题部分。