# WizNote MCP Server（为知笔记私有服务器 MCP）

> English version: [README.en.md](./README.en.md)

把为知笔记私有部署（wiznote/wizserver）的 OpenAPI 封装成 MCP 服务，让支持 MCP 的 Agent 能直接搜索、读写笔记，并把网页（含微信公众号文章 + 内嵌图片）一键收藏为笔记。技术栈为官方 `mcp` SDK + `httpx` + `beautifulsoup4`（网页正文提取）。

所有敏感配置（服务器地址、账号、密码、知识库 GUID）都放在 `.env` 里，**绝不写进代码**。

---

## 功能

| 工具 | 说明 |
|------|------|
| `wiznote_list_folders` | 列出所有笔记文件夹 |
| `wiznote_list_notes` | 列出某文件夹下的笔记（分页/排序） |
| `wiznote_search` | 全文搜索（用 `?ss=` 参数） |
| `wiznote_get_note` | 下载某篇笔记的完整 HTML 正文 |
| `wiznote_create_note` | 新建笔记 |
| `wiznote_update_note` | 更新笔记正文 |
| `wiznote_delete_note` | 删除笔记 |
| `wiznote_save_webpage` | 收藏网页：抓取正文 → 命名 `标题-YYYY-MM-DD`（UTC+8）→ 存入 `/网页收藏/`（可指定） |

### 网页收藏特性
- **普通文章/博客**：用 readability 提取正文。
- **微信公众号文章**（`mp.weixin.qq.com`）：用移动端 UA + Referer 绕过验证页，按
  `#activity-name` / `#js_name` / `#js_content` 提取标题/作者/正文（无需无头浏览器）。
- **图片本地化**：正文里的每张图片会下载并上传为笔记资源，`<img>` 改写为
  `index_files/<name>`，网页端和 Android 客户端都能显示。
- **反爬/验证码**：直接返回失败，不重试、不渲染。

---

## 安装

```bash
git clone <your-repo> wiznote-mcp
cd wiznote-mcp
bash install.sh          # 建 .venv、装依赖、生成 .env（从 .env.example）
```

然后编辑 `.env` 填入真实信息：

```bash
vim .env
```

```dotenv
WIZNOTE_BASE_URL=https://wiznote.yourdomain.com
WIZNOTE_USER_ID=you@your-domain.com     # 私有部署必须用完整邮箱
WIZNOTE_PASSWORD=your-password
WIZNOTE_KB_GUID=                         # 留空则登录时自动发现
```

> 也可以不生成 `.venv`，直接用系统 Python（需自行 `pip install -r requirements.txt`），
> 或让 MCP 宿主直接注入这些环境变量（见下文配置）。

---

## 在 MCP 宿主中注册

服务通过 stdio 通信。把 `command` 指向本项目的 `wiznote.sh`（它会自动加载 `.env`）：

```json
{
  "mcpServers": {
    "wiznote": {
      "command": "/abs/path/to/wiznote-mcp/wiznote.sh",
      "args": []
    }
  }
}
```

若宿主支持 `env` 注入，也可不依赖 `.env`，由宿主传入 `WIZNOTE_*` 变量；本项目 server 会优先使用宿主注入的值。

### Hermes Agent

Hermes 通过 stdio 加载本服务。将 `command` 指向项目的 `wiznote.sh`（自动加载
`.env`），凭据通过 `env` 注入：

```bash
hermes config set mcp_servers.wiznote.command "/abs/path/to/wiznote-mcp/wiznote.sh"
hermes config set mcp_servers.wiznote.args ""
hermes config set mcp_servers.wiznote.env '{"WIZNOTE_BASE_URL": "https://wiznote.yourdomain.com", "WIZNOTE_USER_ID": "you@your-domain.com", "WIZNOTE_PASSWORD": "your-password", "WIZNOTE_KB_GUID": ""}'
hermes gateway restart
```

> `args` 必须留空字符串（Hermes 的 `config set` 会把列表存成字符串，导致 wrapper
> 脚本被正确调用即可规避）。凭据也可改为引用宿主 `.env` 变量（如
> `"WIZNOTE_PASSWORD": "${WIZNOTE_PASSWORD}"`），由 Hermes 启动时展开。

---

## 许可证

MIT