Add Cospend tools — 16 tools for projects, members, bills (OCS) (#52)

Author: oleksandr-nc

PROGRESS.md

@@ -42,14 +42,15 @@
 - [x] File Reminders tools: get_file_reminder, set_file_reminder, remove_file_reminder (2026-04-22)
 - [x] Forms tools: 25 tools covering forms, questions, options, shares, submissions CRUD + export (2026-04-23)
 - [x] Circles (Teams) tools: 14 tools — list/CRUD circles, member add/remove/level, search, join/leave (2026-04-24)
+- [x] Cospend tools: 16 tools — projects (7), members (4), bills (5) — shared expense tracking (2026-04-26)
 
 ### In Progress
 
 ### Blocked
 (none)
 
 ### Next Up
-- Weather Status (fully OCS). Tables, Polls, Notes, Deck, Bookmarks, Photos skipped — API not OCS or OCS incomplete.
+- Cospend follow-ups (Shares: 5 share types; Categories/Payment modes/Currencies; Statistics export). Weather Status (fully OCS, bundled). Tables, Polls, Notes, Deck, Bookmarks, Photos skipped — API not OCS or OCS incomplete.
 
 ## Phases
 
@@ -98,7 +99,8 @@
 | File Reminders | 3 | 20 |
 | Forms | 25 | 34 |
 | Circles | 14 | 31 |
-| **Total** | **141** | **836** |
+| Cospend | 16 | 35 |
+| **Total** | **157** | **871** |
 
 Files shows 10, but one (`upload_file_from_path`) is only registered when
-`NEXTCLOUD_MCP_UPLOAD_ROOT` is configured. Default deployments expose 140 tools.
+`NEXTCLOUD_MCP_UPLOAD_ROOT` is configured. Default deployments expose 156 tools.

README.md

@@ -58,6 +58,7 @@ A 141st tool, `upload_file_from_path`, is registered only when the operator sets
 | [Collectives](#collectives) | list, pages, create, trash, restore | OCS |
 | [Forms](#forms) | CRUD forms, questions, options, shares, submissions + export | OCS |
 | [Circles (Teams)](#circles-teams) | list, CRUD, members (add/remove/promote), join/leave, search | OCS |
+| [Cospend](#cospend) | shared expense tracking — projects, members, bills | OCS |
 | [Unified Search](#unified-search) | list providers, search across apps | OCS |
 | [App Management](#app-management) | list, info, enable, disable apps | OCS |
 
@@ -414,6 +415,29 @@ call; the body is streamed in chunks rather than loaded into memory.
 | `delete_circle` | destructive | Delete a circle |
 | `remove_circle_member` | destructive | Kick a member |
 
+### Cospend
+
+Shared expense tracking ("who paid for what"). Requires the [Cospend](https://apps.nextcloud.com/apps/cospend) app to be installed and enabled. All routes are OCS at `/ocs/v2.php/apps/cospend/api/v1/`.
+
+| Tool | Permission | Description |
+|------|-----------|-------------|
+| `list_cospend_projects` | read | List projects the user can access |
+| `get_cospend_project` | read | Get full project info (members, balance, shares, settings) |
+| `get_cospend_project_statistics` | read | Per-member spending stats (paid/spent/balance) with filters |
+| `get_cospend_project_settlement` | read | Suggested reimbursement transactions to settle a project |
+| `list_cospend_members` | read | List members of a project |
+| `list_cospend_bills` | read | List bills with filters (payer, category, search, pagination) |
+| `get_cospend_bill` | read | Get a single bill |
+| `create_cospend_project` | write | Create a project (caller becomes ADMIN) |
+| `update_cospend_project` | write | Update project name, currency, sort, archive, etc. |
+| `create_cospend_member` | write | Add a member (free-form name or linked to a Nextcloud user) |
+| `update_cospend_member` | write | Update name/weight/color/activated/userid |
+| `create_cospend_bill` | write | Create a bill (defaults date to today if neither date nor timestamp set) |
+| `update_cospend_bill` | write | Update any bill field |
+| `delete_cospend_project` | destructive | Delete a project and all its data |
+| `delete_cospend_member` | destructive | Delete (or soft-disable if member has bills) |
+| `delete_cospend_bill` | destructive | Delete a bill (default: trash; pass `move_to_trash=False` to purge) |
+
 ### Unified Search
 
 | Tool | Permission | Description |

src/nc_mcp_server/server.py

@@ -15,6 +15,7 @@
     collectives,
     comments,
     contacts,
+    cospend,
     files,
     forms,
     mail,
@@ -65,6 +66,7 @@ def create_server(config: Config | None = None) -> FastMCP:
     collectives.register(mcp)
     comments.register(mcp)
     contacts.register(mcp)
+    cospend.register(mcp)
     files.register(mcp)
     forms.register(mcp)
     mail.register(mcp)