cloudsuite

cloudsuite

cloudsuite を使うと、エージェントがセルフホスト可能な Nextcloud インスタンスを操作できます。 ノートの検索と編集、カレンダーの表示とイベントの作成・削除、 連絡先の一覧表示と作成、ファイルの参照・読み取り・書き込み・削除ができます。 ノートにはインスタンスの Notes アプリ API を使用し、カレンダー、連絡先、 ファイルには Nextcloud の CalDAV、CardDAV、WebDAV エンドポイントを使用します。

このパッケージはクリーンルームで再構築されたもので、対象範囲を明示したコアサブセットです。 元の Nextcloud MCP サーバーで説明されている 30 個のツールのうち、15 個をカバーしています。 省略したツールは、以下の「対象範囲」に記載しています。

サービスとの通信方法

各ツールには、3 つの環境変数が必要です。

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

3 つのうち 1 つでも不足している場合、リクエストを送信する前に、不足している変数名を示すエラーですべての呼び出しが失敗します。すべてのリクエストには、ユーザー名とアプリパスワードから作成した 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 はツールに対応しており、各サブコマンドが 1 つのツールに対応します。引数は単一の 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 サーバー

1 つの実行ファイルで、どちらの使い方にも対応します。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（必須）	カレンダーのクエリを 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、6 つすべての nextcloud_tables_* ツール、nextcloud_webdav_search_files、および nextcloud_webdav_create_directory は対象外です。CalDAV/CardDAV のワイヤ形式は 最小限の再構成であり、繰り返しの展開、ETag の処理、タイムゾーンの処理はなく、カレンダーイベント一覧の 抽出も意図的に簡素化されています。このパッケージの構築時に実際の Nextcloud インスタンスは 使用しておらず、動作はフェイク 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 を参照してください。