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

English version: 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 客户端都能显示。
• 反爬/验证码：直接返回失败，不重试、不渲染。

---

安装

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

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

vim .env

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）：

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

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

Hermes Agent

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

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