writedock-mcp 0.0.0-stage → 0.4.2

package/LICENSE-MULTIPOST

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE.md

@@ -0,0 +1,13 @@
+# WriteDock attribution
+
+WriteDock（写作台）is a modified work based in part on [Wechatsync](https://github.com/wechatsync/Wechatsync).
+
+The public platform adapters in `packages/core`, the extension runtime, and portions of DOM preprocessing retain upstream copyright notices and are distributed under the GNU General Public License version 3. See [LICENSE](LICENSE).
+
+The upstream source revision is recorded in [UPSTREAM.json](UPSTREAM.json). Private Wechatsync submodules, proprietary adapters, original branding assets, remote configuration, promotional UI, and analytics are not included.
+
+WriteDock changes include an agent-oriented MCP service, an authenticated loopback bridge, request deduplication, local article previews, account and task management, and offscreen article preprocessing. The transport architecture references the public Wechatsync MCP server package (declared MIT upstream); no private adapter submodule is included.
+
+The MCP SDK, ws, marked, YAML, linkedom, Zod, React, Lucide, DOMPurify, Vite, and other dependencies retain their respective licenses. Dependency licenses are available in their packages.
+
+The creator-page automation for Xiaohongshu and Douyin references the public MultiPost-Extension project (https://github.com/leaperone/MultiPost-Extension), revision 5522ca01100a58572de3a652aebd7851f5fa648a. Its File/DataTransfer upload approach and creator-page selectors are adapted under Apache-2.0; see LICENSE-MULTIPOST. WriteDock adds MCP media grants, bounded chunk transfer, task/result tracking and publication deduplication.

package/README.md

@@ -1,3 +1,102 @@
-# Temporary Holding Version
+# WriteDock MCP
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+连接用户自己的 agent 与 WriteDock 浏览器扩展。agent 写稿并准备图片或视频，本服务负责素材读取、任务转发与结果查询。平台 Cookie 留在浏览器中。
+
+## 通过 npx 连接
+
+电脑需要 Node.js 22+（包含 npm/npx），首次获取及更新需要能访问 npm。无需手动下载解压安装包，无需全局安装。本包运行的是本机 stdio MCP，不是远程托管服务。
+
+```json
+{
+  "mcpServers": {
+    "writedock": {
+      "command": "npx",
+      "args": ["-y", "--prefer-online", "writedock-mcp@latest"],
+      "env": { "WRITEDOCK_PORT": "9647" }
+    }
+  }
+}
+```
+
+Codex 的配置示例（格式依据 [OpenAI 官方 MCP 文档](https://developers.openai.com/codex/mcp/)）：
+
+```toml
+[mcp_servers.writedock]
+command = "npx"
+args = ["-y", "--prefer-online", "writedock-mcp@latest"]
+startup_timeout_sec = 120
+tool_timeout_sec = 60
+
+[mcp_servers.writedock.env]
+WRITEDOCK_PORT = "9647"
+```
+
+不同客户端按各自支持的配置格式添加。首次下载需预留启动时间；Windows 的 npx 启动命令按客户端要求处理。
+
+启动 MCP 后调用 `get_connection_status`；尚未配对时调用 `begin_pairing`，将一次性配对码粘贴到扩展的「MCP 连接」。配对码 3 分钟有效、使用一次失效。连接配置和配对阶段不提交文章；连通后按用户指定的平台和内容调用发布工具。
+
+## 更新与旧版迁移
+
+`--prefer-online` 在每次新启动时检查 npm 包的更新，相同版本可复用缓存；`latest` 指向维护者发布的版本。正在运行的进程不会自动替换，发布新版后重新加载 MCP 连接或重启相关 agent。新建聊天、刷新扩展不一定重启 MCP。
+
+从旧的 `node /安装目录/index.cjs` 迁移时，修改已有 writedock 服务的 command/args，保留原端口、`WRITEDOCK_DATA_DIR`、已有 `WRITEDOCK_TOKEN` 和其他客户端配置，停掉仍运行旧程序的 WriteDock MCP，再重新加载连接。无需删除旧程序目录或配对资料。
+
+身份与配对保存在用户数据目录的 `identity-端口.json`，不在程序目录或 npm 缓存里：
+
+- macOS：`~/Library/Application Support/WriteDock/mcp/`
+- Windows：`%LOCALAPPDATA%/WriteDock/mcp/`
+- Linux：`${XDG_DATA_HOME:-~/.local/share}/writedock/mcp/`
+
+保留同一系统用户、端口和数据目录时，npx 更新继续复用身份。旧 `WRITEDOCK_TOKEN` 仅在首次建立持久身份时迁移，资料已存在时不会覆盖。扩展更新保留浏览器配对；卸载重装扩展后用 `begin_pairing` 恢复，不需要重装 MCP。配对资料不备份浏览器稿件或 Cookie。
+
+服务默认只监听 `127.0.0.1:9647`，可通过 `WRITEDOCK_PORT` 调整。Cookie、稿件与媒体不经过 npm 注册表。MCP 桥接主进程重启后，未完成的本机素材授权需要重新准备，已提交的任务先查询原 request_id，不自动重发。
+
+`npx -y --prefer-online writedock-mcp@latest --version` 只显示版本，不启动服务或读取配对资料。
+
+## 版本提示
+
+自 v0.4.2 起，MCP 在启动后异步检查 npm latest，随后每 6 小时检查，失败后至少等待 10 分钟再试。查询只访问公开版本信息，不传送配对凭据或稿件，也不会阻塞配对、工具调用或发布任务。
+
+`get_connection_status` 返回 `mcp_version`、可用时的 `latest_version`、`update_available`、`update_checked_at`、`update_checking` 及可选 `update_check_error`。运行版本指与扩展实际连接的本机桥接进程；多个 agent 共用端口时，不把新启动客户端的版本误当成仍占用端口的旧服务版本。
+
+现有 ready/ping 消息附带相同信息，扩展显示版本和更新提示。只有确定 npm 版本更新时才提醒用户重新启动 WriteDock MCP。发布任务进行中只提示，不自动重启、改配置或重新提交。旧扩展忽略新增字段；旧 MCP 未提供版本字段时显示未知。npm 查询失败不影响当前连接。
+
+工具包括：`get_connection_status`、`begin_pairing`、`list_platforms`、`check_auth`、`prepare_article`、`publish_article`、`sync_article`、`prepare_post`、`publish_post`、`get_sync_task`、`list_sync_history`。
+
+小红书的三种发布方式共用 `platforms: ["xiaohongshu"]`：
+
+| 模式 | 调用 | 说明 |
+|---|---|---|
+| 写长文 | `publish_article` | Markdown/HTML/稿件文件，支持正文图片，原生自动排版后发布；标题最多 64 字、正文最多 10000 字，不接独立 `cover`、内嵌视频或长文话题 |
+| 普通图文 | `publish_post`，`kind: "image"` | `image_paths`、标题和正文；首图作封面 |
+| 独立视频 | `publish_post`，`kind: "video"` | `video_path`、标题和简介；不传 `cover_path` 时使用平台自动生成的第一帧封面 |
+
+Agent 先看 `list_platforms` 返回的 `publishModes`、`tools`、`modeOptions` 再选入口；直接传内容即可，不要求先准备本机预览。沿用已有工具名称、参数及桥接协议，已有通用 `publish_article` / `publish_post` 的 MCP 无需因小红书增加长文而重装。工具说明源码同步更新，未改用户安装。普通图文/视频的标题、数量、格式和正文长度还受原生控件限制，不能截断或丢图后继续提交。
+
+小红书仅在匹配本任务的 `POST /web_api/sns/v2/note` 返回 HTTP 成功、`success: true`、`result: 0` 和有效笔记 ID 时确认 `submitted`。长文需先核对排版前的完整正文与插图，再核对生成图片的上传及最终长文标记。验证码、协议、封面或设置需人工处理时，Agent 把 `user_actions` 的原因和原稿件链接交给用户，在已打开的同一页处理并手动发布；不重发、不换请求 ID。本次仅完成源码接入，未运行测试、构建、打包或实际投稿。
+
+知乎用 `publish_article` 直接发布 Agent 写好的 Markdown/HTML，参数为 file_path/markdown/html 三选一（或已准备的 draft_id）、platforms: ["zhihu"] 和稳定 request_id。可直接提交，无需在扩展编写，也无需先调用 prepare_article。支持本地 PNG/JPEG/GIF/WebP 正文图片；稿件中的 `<video src="./demo.mp4"></video>` 可插入本地 MP4，路径按稿件目录或 base_directory 解析。每篇最多 5 个视频、总量 512 MB；标题最多 100 字，独立封面和话题暂未接入。视频是文章内嵌，不是独立视频投稿。
+
+扩展自动完成知乎内部草稿准备，再触发页面原生发布，让平台生成动态签名；仅在发布接口返回 code=0 且文章 ID 匹配时确认 submitted。未知结果返回 unknown，不自动重发。返回 task_id 后调用 get_sync_task 查询。源码接入尚未运行测试或真实投稿。
+
+百家号同样使用 `publish_article`，必须提供 cover 封面（本地图片、HTTP(S) 地址或 data URI），当前接收 64 字以内标题，暂不接文章内视频。平台要求旋转验证码、其他验证码或调整封面时，任务返回 needs_user_action，顶层 requires_user_action 和 user_actions 给出原因、原稿件链接。Agent 必须把它们告诉用户，优先让用户在扩展已打开的页面完成验证并手动发布，不解验证码、不重发、不换 ID。人工接管不会被标记为提交成功，原任务也不会自动确认用户之后的操作。
+
+微博长文章同样用 `publish_article`，platforms: ["weibo"]；当前接收 32 字以内标题，正文支持图片、封面可选。无独立封面时使用本篇第一张正文图片，没有正文图片则需显式提供 cover。视频 URL 尚未接入。验证码、原创协议或发布设置无法核对时转人工处理；不自动关注官方账号、声明原创或同步新浪新闻。
+
+微信公众号、搜狐号暂用 `sync_article` 保存草稿。B站专栏改用 `publish_article`，平台 ID 为 `bilibili`，`platforms: ["bilibili"]` 接收 Agent 的 Markdown/HTML/文件，支持正文图片。扩展使用新版原生编辑器生成实时签名、上传图片并直接提交；不经过旧版专栏草稿接口。B站暂不接视频、视频卡片、音频或独立 cover，标题按页面实际限制校验。`code=-352` 或验证码请求返回 needs_user_action 和当前原稿件页链接，让用户在已打开的标签页验证并手动发布，Agent 不重新提交。只有匹配的 create/opus 返回 code=0 及有效字符串 dyn_id_str 才报告 submitted。B站接入沿用现有工具和平台字符串参数，不增加 MCP 工具、参数或协议，无需因此重装 MCP。微博长文章保留并接入直发。知乎、百家号、微博长文章、B站专栏旧草稿请求不会自动公开发布，需显式使用 publish_article。实际能力以 list_platforms 的 action、publishModes、capabilities、coverRequired 为准，publish_article 的平台入参不固定枚举。
+
+小红书、抖音、微博普通图文/独立视频用 `prepare_post` / `publish_post`。字段包括 kind（image/video）、title、content、image_paths、video_path、cover_path、tags、base_directory。路径由 agent 自动准备。图片单张 20 MB、总量 100 MB；视频最大 512 MB，支持 MP4/MOV/WebM，具体格式和数量以平台上传控件为准。视频封面可选，图文封面使用第一张图片。普通微博标题放在正文首行，最多 18 张图片；微博视频封面最多 5 MB、标题最多 30 个汉字或 60 个半角字符。
+
+抖音 `platforms: ["douyin"]` 直接复用 MultiPost-Extension 的公开页面流程，用户不需要先操作发布或抓 HAR。图文用 `kind: "image"`，独立视频用 `kind: "video"`，可选 `cover_path`。当前图文话题最多 4 个、视频最多 5 个；标题、全文和话题写入后会完整核对。仅接即时投稿，工具未提供定时发布或横竖两套封面参数。抖音以本次操作新增的原生成功提示确认 `submitted`，`list_platforms.confirmation` 为 `native_page_message`；未核对最终 HTTP 业务回执，跳转本身不算成功，没有明确提示则返回 `unknown`。验证码、声明、协议和封面问题返回 `needs_user_action`，Agent 交出原投稿页和原因，让用户在同一页处理并手动发布，不重发。本次沿用现有 `publish_post` 及桥接协议，已有此工具的 MCP 无需因此重装；仅改源码，未运行测试、构建、打包或修改用户安装。
+
+微博视频必须明确 `weibo_video_creation: original | secondary | repost`（原创/二创/转载），不得默认声明原创。此参数会保存到本机稿件并参与请求去重。若需补充来源、原视频关联、内容声明、分类、封面或验证码，返回 needs_user_action 及原投稿页链接，Agent 告诉用户在已打开的页面手动处理并发布，不重新提交。只有匹配本任务的 statuses/update 成功回执才确认微博 submitted；视频回执可能不带帖子 ID，不因此编造 ID。微博长文章继续用 publish_article，三种格式共用 weibo 这个平台 ID。
+
+先用 `prepare_post` 存本机预览，返回 draft_id；再向 `publish_post` 传 draft_id、request_id 和 platforms（xiaohongshu/douyin/weibo）。也可直接向 publish_post 提供全部内容与素材。该工具会打开平台原生页面并点击发布，必须以用户明确的发布要求和目标平台为依据。publish_post 的平台参数改为由扩展实际能力校验，不在 MCP 中固定枚举。
+
+所有提交都需要稳定的 `request_id`，返回 `task_id` 后用 `get_sync_task` 跟进。同 ID 的相同请求复用原任务，不能用同 ID 发布不同内容。Agent 只使用 WriteDock MCP，不依赖浏览器或 Playwright 工具。打开平台原生投稿页及操作由扩展完成。任务返回 finished、next_action、results、agent_instructions；poll_task 按原 ID 继续查询，report_result 汇报逐平台结果和链接。submitted/published 后不再打开网站验证；验证码、图形验证、unknown 或 interrupted 时，把 user_actions 中的原因和链接交给用户自行点击处理，不自动换 ID 重试。submitted 表示平台接受提交，是否公开展示以平台审核为准。
+
+本地视频不嵌入 MCP 消息，而是通过随机授权、绑定具体文件的本机 HTTP 范围请求分块传输。授权两小时有效，MCP 桥接主进程重启后重新准备素材；文件变更会拒绝读取。从旧版使用新增 publish_article 或 prepare_post/publish_post 工具时，原位升级本 MCP 一次并重启，保留 agent 配置和已有配对资料。
+
+本次微博接入新增创作类型参数，并放开 publish_post 的固定平台枚举，启用新版时需原位更新 MCP 程序一次。后续同类平台增删由扩展校验，避免每次改平台枚举；保留安装位置、启动配置和配对资料，无需卸载重装。本版本提供可通过 npx 启动的构建包，未进行真实平台投稿验证。
+
+对应源码位于 npm 包内 `source/`，可在该目录安装开发依赖并运行构建命令。第三方依赖许可见 `THIRD_PARTY_NOTICES.txt`，本服务遵循 GPL-3.0-only，见 `LICENSE` 与 `NOTICE.md`。