# 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 配置路径正确

更多问题请查看[常见问题](#常见问题)部分。