Metadata-Version: 2.4
Name: mtk-online-mcp
Version: 0.1.0
Summary: MCP server: browser login to MTK Online and fetch authenticated pages.
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: mcp>=1.2.0
Requires-Dist: playwright>=1.49.0
Requires-Dist: pypdf>=5.0.0

# MTK Online MCP

通过 Playwright 登录 [MTK Online](https://online.mediatek.com/)，在 Cursor 中通过 MCP 抓取页面、按约定优先级搜索，并在用户确认后下载 DCC PDF。

## 模型 / 助手操作规程（必读）

1. **一般内容查询**  
   优先调用 **`mtk_search_priority`**。服务端按固定顺序返回四类搜索页的可见文本：**FAQ → Quick Start → eCourse → eService**。回答用户时应**优先采用靠前段落**（尤其 FAQ / Quick Start），再视需要引用后面段落。

2. **已知 FAQ 编号**  
   使用 **`mtk_fetch_faq_detail`**（`faq_id` 可为 `33353` 或 `FAQ33353`；`list_name` 与站点分类一致，默认 `Modem`）。

3. **DCC 文档（强制两步）**  
   - **第一步**：仅用 **`mtk_search_dcc`** 展示搜索结果列表（可翻页：`page_index`，每页 10 条）。**不要**在未确认前调用下载。  
   - **第二步**：用户明确确认目标条目的 **`dcc_id`**（如 `DCC3290136`）和**与页面完全一致的 `document_title`（含 `.pdf`）** 后，再调用 **`mtk_download_dcc_pdf`**，且 **`confirmed` 必须为 `true`**。  
   若标题与页面不一致，点击下载会失败。

4. **任意 HTTPS 链接**  
   使用 **`mtk_fetch_page`**。若目标为 `eservice.mediatek.com`，MCP 会在 eService 门户尝试二次登录。

## 工具一览

| 工具 | 用途 |
|------|------|
| `mtk_search_priority` | 按 FAQ→Quick Start→eCourse→eService 依次搜索同一关键词 |
| `mtk_fetch_faq_detail` | 打开指定 FAQ 详情页 |
| `mtk_search_dcc` | 仅在 DCC 中搜索，仅列表、不下载 |
| `mtk_download_dcc_pdf` | 用户确认后下载 DCC PDF，可选解密预览 |
| `mtk_fetch_page` | 登录后打开任意 URL 并返回正文可见文本 |

## 环境变量

| 变量 | 说明 |
|------|------|
| `MTK_ONLINE_EMAIL` | 必填，登录邮箱 |
| `MTK_ONLINE_PASSWORD` | 必填，密码 |
| `MTK_ONLINE_OTP` | 可选，一次性验证码（若登录页需要） |
| `MTK_ONLINE_LOGIN_URL` | 可选，默认 `https://online.mediatek.com/` |
| `MTK_ONLINE_HEADLESS` | 可选，`0` / `false` 为有头浏览器，默认 headless |
| `MTK_ONLINE_TIMEOUT_MS` | 可选，超时毫秒数，默认 `60000` |
| `MTK_DCC_DOWNLOAD_DIR` | 可选，DCC PDF 保存目录；未设则用 `%TEMP%\mtk_dcc_downloads` |
| `MTK_DOC_PASSWORD` | 可选，加密 PDF 解密密码（也可通过工具参数 `pdf_password` 传入） |

建议在 Cursor 的 MCP 配置 `env` 中写入凭据，或使用系统环境变量。

## 安装

推荐使用项目内可编辑安装（与 `pyproject.toml` 一致，含 `pypdf`）：

```powershell
cd "G:\AI\cursor\mtk online"
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -e .
playwright install chromium
```

若仅用 `requirements.txt`，安装后请确保已安装 `pypdf`（DCC 解密预览需要）。

### Playwright 浏览器（所有方式都要做一次）

本机**只需安装一次** Chromium（装到用户目录，与各虚拟环境共用）：

```powershell
playwright install chromium
```

若尚未全局安装过 Playwright CLI，可先：`pip install playwright`，再执行上句；或使用已安装项目虚拟环境里的 `playwright` 命令。

## 像 npx / uvx 一样：不写项目路径

原理与 `chrome-devtools`（npx 拉包）、`windows-mcp`（uvx 拉包）相同：**把 `mtk-online-mcp` 发布到 PyPI（或可被 uv 拉取的 Git 仓库）**，Cursor 里只配 `command` + `args` + `env`，**不需要 `cwd`、不需要压缩包**。

### 1）包已发布到 PyPI 时（推荐）

本仓库已在 `pyproject.toml` 中注册命令行入口 `mtk-online-mcp`。发布示例：

```powershell
pip install build twine
python -m build
twine upload dist/*
```

使用者 `mcp.json`（需已安装 [uv](https://docs.astral.sh/uv/)，且本机已 `playwright install chromium`）：

```json
{
  "mcpServers": {
    "mtk-online": {
      "command": "uvx",
      "args": ["--from", "mtk-online-mcp>=0.1.0", "mtk-online-mcp"],
      "env": {
        "MTK_ONLINE_EMAIL": "your@email",
        "MTK_ONLINE_PASSWORD": "your-password"
      }
    }
  }
}
```

`uvx` 会自动下载 wheel 到缓存并启动；**勿把密码提交到 Git**。

### 2）未发 PyPI，只用公司 Git 仓库时

将代码推到可访问的 Git 地址后，他人可用（把 URL、分支或 tag 换成实际值）：

```json
{
  "mcpServers": {
    "mtk-online": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/YOUR_ORG/mtk-online-mcp.git@v0.1.0",
        "mtk-online-mcp"
      ],
      "env": {
        "MTK_ONLINE_EMAIL": "your@email",
        "MTK_ONLINE_PASSWORD": "your-password"
      }
    }
  }
}
```

私有仓库需带 token 的 URL 或本机已配置 Git 凭据；具体以公司安全规范为准。

### 3）仍用本地克隆目录（开发调试用）

与最初方式相同：指定 `venv` 里的 `python.exe` + `cwd`，见下一节。

## Cursor MCP 配置示例（本地开发）

在 Cursor 的 MCP 设置中增加类似项（路径按本机修改）：

```json
{
  "mcpServers": {
    "mtk-online": {
      "command": "python",
      "args": ["-m", "mtk_online_mcp"],
      "cwd": "G:\\AI\\cursor\\mtk online",
      "env": {
        "MTK_ONLINE_EMAIL": "your@email",
        "MTK_ONLINE_PASSWORD": "your-password"
      }
    }
  }
}
```

也可把 `command` 改为虚拟环境里的 `python.exe`，与上图一致。

修改代码或依赖后，请在 Cursor 中**重启**该 MCP 服务。

## 说明

- 优先级搜索每类结果有长度上限，过长会截断并提示。  
- `mtk_fetch_page` 单页正文过长时也会截断。  
- DCC 下载依赖浏览器下载能力；解密预览依赖 `pypdf`。
