collabnotes

collabnotes

collabnotes 可处理 HackMD 中的协作笔记：读取已通过身份验证的用户的个人资料、团队和阅读历史，列出团队笔记和个人笔记，并在这两处创建、更新和删除笔记。它会使用你提供的个人 API 令牌，代表你调用公开的 HackMD API v1。

此软件包是一次从头构建的实现，涵盖原版 HackMD MCP 服务的全部已记录工具（共 12 个）。

与服务的通信方式

每个工具都需要 HackMD API 令牌：

export HACKMD_API_TOKEN="your token"
# Optional override (default: https://api.hackmd.io/v1)
export HACKMD_API_URL="https://api.hackmd.io/v1"

如果未设置令牌，每次调用都会在发出任何请求之前失败，并报错指出 HACKMD_API_TOKEN。

请求会携带 Authorization: Bearer HACKMD_API_TOKEN。团队路径和笔记 ID 等路径片段会进行 URL 编码。响应会以解析后的 JSON 返回；删除调用和空响应正文会返回包含相关 ID 的 {"status": "ok", ...}，上游 HTTP 错误则会报告其状态码和正文。请注意，HackMD API 的创建/更新权限字段不属于此工具规范：创建时只发送 title 和 content，更新时只发送 content。

安装

npx @reneturcios/collabnotes list_user_notes '{}'

也可以运行容器镜像：

docker run -i ghcr.io/cloudcorprecords/collabnotes

容器默认启动 MCP 服务。传入 CLI 参数即可将其用作 CLI。

CLI

CLI 与这些工具一一对应：每个工具都有一个子命令，并将参数作为单个 JSON 对象传入。

collabnotes get_user_info '{}'
collabnotes list_teams '{}'
collabnotes get_history '{}'
collabnotes list_team_notes '{"teamPath":"my-team"}'
collabnotes create_team_note '{"teamPath":"my-team","title":"Spec","content":"# Spec"}'
collabnotes update_team_note '{"teamPath":"my-team","noteId":"abc","content":"# v2"}'
collabnotes delete_team_note '{"teamPath":"my-team","noteId":"abc"}'
collabnotes list_user_notes '{}'
collabnotes get_note '{"noteId":"abc"}'
collabnotes create_note '{"title":"Note","content":"# Note"}'
collabnotes update_note '{"noteId":"abc","content":"# v2"}'
collabnotes delete_note '{"noteId":"abc"}'
collabnotes --version

退出代码：成功时为 0，API 或验证错误时为 1（错误信息会指出问题），用法错误时为 2。

MCP 服务

同一个可执行文件同时支持这两种模式。mcp 子命令会启动 stdio MCP 服务：

npx -y @reneturcios/collabnotes mcp

MCP 客户端配置：

{
  "mcpServers": {
    "collabnotes": {
      "command": "npx",
      "args": ["-y", "@reneturcios/collabnotes", "mcp"],
      "env": { "HACKMD_API_TOKEN": "your token" }
    }
  }
}

工具

工具	输入	功能
get_user_info	（无）	获取已通过身份验证的 HackMD 用户信息。（GET /me）
list_teams	（无）	列出已通过身份验证的用户所属团队。（GET /teams）
get_history	（无）	获取已通过身份验证的用户的笔记阅读历史。（GET /history）
list_team_notes	teamPath（必填）	列出属于某个团队的笔记。
create_team_note	teamPath、title、content（均必填）	在团队中创建新笔记。
update_team_note	teamPath、noteId、content（均必填）	更新团队笔记的内容。
delete_team_note	teamPath、noteId（必填）	删除团队笔记。
list_user_notes	（无）	列出已通过身份验证的用户自己的笔记。（GET /notes）
get_note	noteId（必填）	根据 ID 获取单条笔记。
create_note	title、content（必填）	创建新的个人笔记。
update_note	noteId、content（必填）	更新个人笔记的内容。
delete_note	noteId（必填）	删除个人笔记。

开发

npm install
npm run build   # tsc -> dist/
npm test        # node test runner over test/*.test.ts, fake fetch only, no network
npm run dev     # run the CLI from source via tsx

许可证

MIT — 详见 LICENSE。