WonderPen 使用手册

外观

HTTP API、MCP 与命令行接口 ​

WonderPen 桌面版提供本地 HTTP API、MCP 和命令行接口（CLI），可供脚本或支持 MCP 的应用访问文档库内容。

提示

HTTP API 自桌面版 v3.1.3 开始支持。不同版本提供的命令可能不同，请以当前应用中的设置和帮助信息为准。

开启服务 ​

在【设置】→【高级】→【API】中打开启用 API HTTP 服务。服务默认关闭，默认端口为 8022，只监听本机地址 127.0.0.1，不能由另一台电脑直接通过局域网访问。

使用接口期间，请保持 WonderPen 运行，并打开需要操作的文档库。HTTP、MCP 和 CLI 都只能访问当前已打开的文档库；即使指定了库路径或标识符，也不能直接访问未打开的库。

开启后，检查设置页中的服务状态。运行时会显示可复制的 MCP 地址；端口需要在服务停止时修改。

鉴权与接口权限 ​

设置页提供 API Token 的显示、复制和重设功能。调用需要鉴权的接口时，将它作为请求头发送：

http
Authorization: Bearer wp-xxx

将 wp-xxx 替换为你自己的 Token。重设 Token 后，需要同时更新已连接应用中的配置。Token 可用于访问你的数据，请勿把真实 Token 写进公开脚本或分享截图。

接口权限可选择：

  • 只读：允许读取，拒绝创建、修改、删除、移动以及修改设置等写入操作。
  • 读写：允许读取和写入，但仍受功能权限与文档正文锁定等限制。

当前默认权限为读写。如果只需要检索或参考内容，可先改为只读。这个设置同时作用于 HTTP、MCP 和 CLI。

Token 操作与接口权限

HTTP 连接示例 ​

以下示例只读取信息，不修改文档。使用自定义端口时，请替换地址中的 8022。示例使用 curl；Windows PowerShell 中可使用 curl.exe 调用同一工具。

先检查服务是否能连接：

sh
curl http://127.0.0.1:8022/

正常情况下返回 Hello WonderPen!。这个健康检查不需要 Token；返回成功只说明服务可连接，不表示鉴权已通过。

再携带 Token 获取命令帮助：

sh
curl -H "Authorization: Bearer wp-xxx" http://127.0.0.1:8022/api/cli/help

这个接口需要鉴权，会返回当前版本支持的 CLI 命令帮助。HTTP 数据操作通过 POST /api/data 调用，设置操作通过 POST /api/setting 调用；接入脚本时应先确认目标文档库及具体操作参数。

MCP 服务 ​

MCP（Model Context Protocol）让支持它的 AI 应用连接外部工具。WonderPen 提供 MCP 接口，AI 服务由你连接的第三方应用提供。

开启 API HTTP 服务后，MCP 服务同时可用，不需要另行开启 CLI。连接参数如下：

参数内容
类型Streamable HTTP
地址设置页显示的 MCP 地址，默认 http://127.0.0.1:8022/mcp
请求头名称Authorization
请求头值Bearer wp-xxx，替换为自己的 API Token

不同客户端的配置字段名称可能不同，请按其 Streamable HTTP 接入方式填写。有些客户端把请求头名称和值分开填写；如果使用 名称=值 的格式，则填写 Authorization=Bearer wp-xxx。

连接后可先让客户端列出可访问的文档库或读取一篇测试文档。客户端必须能够访问运行 WonderPen 的这台电脑；运行在远端服务器上的连接器无法直接访问你的 127.0.0.1。授权第三方 AI 应用读取内容后，其后续处理遵循该应用的服务规则。

CLI ​

通过 WonderPen 自带的命令行接口读写数据或设置时，需要同时开启 API HTTP 服务和CLI 服务。CLI 服务默认关闭。

开启后，设置页会显示可复制的 CLI 示例命令，其中包含当前安装位置对应的可执行文件路径。可复制到终端运行以查看帮助；Windows PowerShell 中需在带引号的可执行文件路径前加上调用运算符 &。通用形式如下：

sh
WonderPen --cli help
WonderPen --cli status

这里的 WonderPen 代表应用的可执行文件，不一定能直接从终端找到，请使用设置页提供的实际路径。内置 CLI 会自动读取本机服务的端口和 Token，无需手动添加请求头。

help 显示命令用法，即使服务未开启也能运行，不能据此判断连接成功。status 用于查看服务状态和接口权限；如果无法连接服务，会显示本地状态及相应提示。

例如，在 Windows PowerShell 中（路径请替换为实际安装位置）：

powershell
& "C:\实际安装路径\WonderPen.exe" --cli help

常见连接问题 ​

现象检查方法
无法连接或连接被拒绝确认 WonderPen 正在运行、API 服务已开启且状态正常，地址和端口与设置页一致
401 unauthorized检查 Token 和 Authorization 请求头；重设 Token 后更新客户端配置
read_only_mode当前权限为只读；确实需要写入时，在 WonderPen 设置中切换为读写
CLI 不可用确认 API HTTP 服务和 CLI 服务都已开启，并使用正确的可执行文件路径
no_target_library先打开需要操作的文档库；打开多个库时，按命令帮助指定目标库
library_access_denied确认目标文档库当前已打开；云端库还须属于当前登录账号
端口被占用（EADDRINUSE）关闭 API 服务，换一个未被占用的端口后重新开启，并更新客户端地址

参考 ​