# cloudsuite

cloudsuite lets an agent work with a self-hosted Nextcloud instance:
search and edit notes, see calendars and create or delete events,
list and create contacts, and browse, read, write, and delete files.
Notes go through the instance's Notes app API; calendars, contacts,
and files go through Nextcloud's CalDAV, CardDAV, and WebDAV
endpoints.

This package is a clean-room rebuild, and a **labelled core subset**:
it covers 15 of the 30 tools documented for the original Nextcloud
MCP server. The omitted tools are listed under "Scope" below.

## How it talks to the service

Every tool needs three environment variables:

```bash
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
```

With any of the three missing, every call fails with an error naming
the missing variables, before any request is made. Every request
carries HTTP Basic auth built from the username and app password.

**Wire-format note:** the original project's README documents the
tools and their purposes; the endpoint shapes here follow Nextcloud's
public Notes API and DAV layout. Notes use
`{NEXTCLOUD_URL}/index.php/apps/notes/api/v1`; calendars use CalDAV
under `{NEXTCLOUD_URL}/remote.php/dav/calendars/{user}/`; contacts
use CardDAV under
`{NEXTCLOUD_URL}/remote.php/dav/addressbooks/users/{user}/`; files
use WebDAV under `{NEXTCLOUD_URL}/remote.php/dav/files/{user}/`.
Path segments are percent-encoded per segment (slashes preserved).
DAV status 207 counts as success; any other non-2xx response is
reported with its status and a body excerpt. Calendar event listing
is a summary only: the REPORT response is reduced to its status, byte
count, and the `SUMMARY:` lines found in it.

## Install

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

Or run the container image:

```bash
docker run -i ghcr.io/cloudcorprecords/cloudsuite
```

The container defaults to the MCP server. Pass CLI arguments to use
it as a CLI instead.

## CLI

The CLI mirrors the tools: one subcommand per tool, taking its
arguments as a single JSON object.

```bash
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
```

Exit codes: `0` on success, `1` on an API or validation error (the
error names the problem), `2` for usage errors.

## MCP server

One bin serves both faces. The `mcp` subcommand starts a stdio MCP
server:

```bash
npx -y @reneturcios/cloudsuite mcp
```

MCP client configuration:

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

### Tools

| Tool | Input | What it does |
| --- | --- | --- |
| `nextcloud_notes_search_notes` | `query` (required) | Fetch all notes and keep those whose title or content contains the query (case-insensitive). |
| `nextcloud_notes_create_note` | `title`, `content` (required), `category` | Create a note via the Notes API. |
| `nextcloud_notes_update_note` | `id` (required), `title`, `content`, `category` | Update the provided fields of a note. |
| `nextcloud_notes_append_content` | `id`, `content` (required) | Read the note, then write it back with the new content appended after a newline; the title is preserved. |
| `nextcloud_notes_delete_note` | `id` (required) | Delete a note; returns `{status, id}`. |
| `nextcloud_calendar_list_calendars` | — | PROPFIND the calendars root and return each collection's display name and href. |
| `nextcloud_calendar_create_event` | `calendarId`, `summary`, `dtstart`, `dtend` (required), `description`, `location` | PUT a generated VEVENT as an `.ics` file into the calendar; returns `{status, uid}`. |
| `nextcloud_calendar_list_events` | `calendarId` (required) | REPORT a calendar-query and summarize the response: status, bytes, and extracted `SUMMARY:` lines. |
| `nextcloud_calendar_delete_event` | `calendarId`, `eventId` (required) | DELETE the event resource. |
| `nextcloud_contacts_list_contacts` | `addressBookId` (required) | PROPFIND an address book and return the hrefs it contains. |
| `nextcloud_contacts_create_contact` | `addressBookId`, `fullName` (required), `email`, `phone`, `organization` | PUT a generated VCARD as a `.vcf` file into the address book; returns `{status, uid}`. |
| `nextcloud_webdav_list_directory` | `path` (required) | PROPFIND a folder and return each entry's name, href, and whether it is a collection. |
| `nextcloud_webdav_read_file` | `path` (required) | GET a file and return its text content and byte count. |
| `nextcloud_webdav_write_file` | `path`, `content` (required) | PUT text content to a file path. |
| `nextcloud_webdav_delete_resource` | `path` (required) | DELETE a file or folder. |

## Scope

Omitted from this core subset: `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`, all six `nextcloud_tables_*`
tools, `nextcloud_webdav_search_files`, and
`nextcloud_webdav_create_directory`. The CalDAV/CardDAV wire shapes
are minimal reconstructions: there is no recurrence expansion, ETag
handling, or timezone processing, and the calendar event listing
extraction is intentionally crude. No live Nextcloud instance was
used while building this package; behaviour is covered by fake-fetch
tests only.

## Development

```bash
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
```

## License

MIT — see `LICENSE`.