cloudsuite

cloudsuite

cloudsuite 可让 Agent 与可自托管的 Nextcloud 实例交互： 搜索和编辑笔记、查看日历并创建或删除事件、 列出和创建联系人，以及浏览、读取、写入和删除文件。 笔记通过实例的 Notes 应用 API 操作；日历、联系人 和文件则分别通过 Nextcloud 的 CalDAV、CardDAV 和 WebDAV 端点操作。

此软件包是一个从零独立重建的版本，包含一个标注过的核心子集： 涵盖原始 Nextcloud MCP 服务文档中 30 个工具里的 15 个。 未包含的工具列在下文的“范围”部分。

与服务的通信方式

每个工具都需要三个环境变量：

export NEXTCLOUD_URL="https://cloud.example.com"   # base URL of the instance
export NEXTCLOUD_USERNAME="alice"
export NEXTCLOUD_PASSWORD="xxxxx-xxxxx-xxxxx-xxxxx"  # an app password

缺少其中任何一个变量时，每次调用都会报错并指出缺失的变量，且不会发送任何请求。每个请求都使用用户名和应用密码构造 HTTP Basic 身份验证。

线路格式说明： 原项目的 README 文档介绍了各工具及其用途；此处的端点格式遵循 Nextcloud 的公开 Notes API 和 DAV 布局。笔记使用 {NEXTCLOUD_URL}/index.php/apps/notes/api/v1；日历使用位于 {NEXTCLOUD_URL}/remote.php/dav/calendars/{user}/ 下的 CalDAV； 联系人使用位于 {NEXTCLOUD_URL}/remote.php/dav/addressbooks/users/{user}/ 下的 CardDAV； 文件使用位于 {NEXTCLOUD_URL}/remote.php/dav/files/{user}/ 下的 WebDAV。 路径段会分别进行百分号编码（保留斜杠）。 DAV 状态码 207 视为成功；其他非 2xx 响应会报告状态码和正文摘录。日历事件列表仅提供摘要：REPORT 响应会缩减为其状态、字节数以及其中找到的 SUMMARY: 行。

安装

npx @reneturcios/cloudsuite nextcloud_webdav_list_directory '{"path":"/"}'

也可以运行容器镜像：

docker run -i ghcr.io/cloudcorprecords/cloudsuite

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

CLI

CLI 与各工具一一对应：每个工具都有一个子命令，其参数为单个 JSON 对象。

cloudsuite nextcloud_notes_search_notes '{"query":"shopping"}'
cloudsuite nextcloud_notes_create_note '{"title":"Ideas","content":"..."}'
cloudsuite nextcloud_calendar_list_calendars '{}'
cloudsuite nextcloud_webdav_read_file '{"path":"/Documents/notes.txt"}'
cloudsuite --version

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

MCP 服务

同一个可执行文件提供两种用法。mcp 子命令会启动 stdio MCP 服务：

npx -y @reneturcios/cloudsuite mcp

MCP 客户端配置：

{
  "mcpServers": {
    "cloudsuite": {
      "command": "npx",
      "args": ["-y", "@reneturcios/cloudsuite", "mcp"],
      "env": {
        "NEXTCLOUD_URL": "https://cloud.example.com",
        "NEXTCLOUD_USERNAME": "alice",
        "NEXTCLOUD_PASSWORD": "your app password"
      }
    }
  }
}

工具

工具	输入	功能
nextcloud_notes_search_notes	query（必需）	获取所有笔记，并保留标题或内容包含查询词的笔记（不区分大小写）。
nextcloud_notes_create_note	title、content（必需）、category	通过 Notes API 创建笔记。
nextcloud_notes_update_note	id（必需）、title、content、category	更新笔记中提供的字段。
nextcloud_notes_append_content	id、content（必需）	读取笔记，然后在换行符后附加新内容并写回；保留标题。
nextcloud_notes_delete_note	id（必需）	删除笔记；返回 {status, id}。
nextcloud_calendar_list_calendars	—	对日历根目录执行 PROPFIND，并返回每个集合的显示名称和 href。
nextcloud_calendar_create_event	calendarId、summary、dtstart、dtend（必需）、description、location	将生成的 VEVENT 作为 .ics 文件 PUT 到日历中；返回 {status, uid}。
nextcloud_calendar_list_events	calendarId（必需）	执行 calendar-query REPORT，并汇总响应：状态、字节数和提取出的 SUMMARY: 行。
nextcloud_calendar_delete_event	calendarId、eventId（必需）	DELETE 事件资源。
nextcloud_contacts_list_contacts	addressBookId（必需）	对通讯录执行 PROPFIND，并返回其中包含的 href。
nextcloud_contacts_create_contact	addressBookId、fullName（必需）、email、phone、organization	将生成的 VCARD 作为 .vcf 文件 PUT 到通讯录中；返回 {status, uid}。
nextcloud_webdav_list_directory	path（必需）	对文件夹执行 PROPFIND，并返回每个条目的名称、href 以及其是否为集合。
nextcloud_webdav_read_file	path（必需）	GET 文件，并返回其文本内容和字节数。
nextcloud_webdav_write_file	path、content（必需）	将文本内容 PUT 到文件路径。
nextcloud_webdav_delete_resource	path（必需）	DELETE 文件或文件夹。

范围

此核心子集中省略了：hello、 nextcloud_calendar_get_event、nextcloud_calendar_update_event、 nextcloud_contacts_list_addressbooks、 nextcloud_contacts_create_addressbook、 nextcloud_contacts_delete_addressbook、 nextcloud_contacts_delete_contact、全部六个 nextcloud_tables_* 工具、nextcloud_webdav_search_files，以及 nextcloud_webdav_create_directory。CalDAV/CardDAV 在线格式 仅为最小化重构：不支持重复事件展开、ETag 处理或时区处理，日历事件列表的提取逻辑也有意保持粗略。构建此软件包时未使用真实的 Nextcloud 实例；行为仅由 fake-fetch 测试覆盖。

开发

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。