Skip to content

Commit 546f93c

Browse files
committed
Update README with all 30 tools, add badges (Nextcloud, MIT), enable 7 new ruff rule sets, simplify PL/C config
1 parent a69e3b7 commit 546f93c

2 files changed

Lines changed: 88 additions & 16 deletions

File tree

README.md

Lines changed: 78 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -5,21 +5,24 @@
55
[![Integration Tests](https://github.com/cloud-py-api/nc-mcp-server/actions/workflows/tests-integration.yml/badge.svg)](https://github.com/cloud-py-api/nc-mcp-server/actions/workflows/tests-integration.yml)
66
[![codecov](https://codecov.io/gh/cloud-py-api/nc-mcp-server/graph/badge.svg)](https://codecov.io/gh/cloud-py-api/nc-mcp-server)
77

8+
![NextcloudVersion](https://img.shields.io/badge/Nextcloud-32%20%7C%2033-blue)
89
![PythonVersion](https://img.shields.io/badge/python-3.12%20%7C%203.13%20%7C%203.14-blue)
9-
[![PyPI](https://img.shields.io/pypi/v/nc-mcp-server.svg)](https://pypi.org/project/nc-mcp-server/)
1010
[![Python](https://img.shields.io/pypi/implementation/nc-mcp-server)](https://pypi.org/project/nc-mcp-server/)
11+
[![PyPI](https://img.shields.io/pypi/v/nc-mcp-server.svg)](https://pypi.org/project/nc-mcp-server/)
12+
[![License: MIT](https://img.shields.io/github/license/cloud-py-api/nc-mcp-server)](https://github.com/cloud-py-api/nc-mcp-server/blob/main/LICENSE)
1113

1214
> **Experimental** — This repository is fully maintained by AI (Claude). It serves as an experiment in autonomous AI-driven open-source development.
1315
1416
An [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) server that exposes Nextcloud APIs as tools for AI assistants. Connect any MCP-compatible client (Claude Desktop, Claude Code, etc.) to your Nextcloud instance and let AI manage files, read notifications, interact with Talk, and more.
1517

1618
## Features
1719

18-
- **File Management** — List, read, upload, move, and delete files via WebDAV
20+
- **File Management** — List, read, search, upload, move, and delete files via WebDAV
1921
- **User Info** — Get current user, list users, view user details
20-
- **Notifications** — List and dismiss notifications (coming soon)
21-
- **Activity Feed** — View recent activity (coming soon)
22-
- **Talk** — List conversations, read and send messages (coming soon)
22+
- **Notifications** — List and dismiss notifications
23+
- **Activity Feed** — View recent activity with filtering and pagination
24+
- **Talk** — List conversations, read and send messages, manage polls
25+
- **Comments** — List, add, edit, and delete file comments
2326
- **Security-First** — Granular permission levels control what AI can do
2427

2528
## Security: Permission Model
@@ -40,6 +43,13 @@ If a tool is called without sufficient permission, it returns a clear error expl
4043
pip install nc-mcp-server
4144
```
4245

46+
Or with `pipx` / `uvx` for isolated installation:
47+
```bash
48+
pipx install nc-mcp-server
49+
# or
50+
uvx nc-mcp-server
51+
```
52+
4353
Or from source:
4454
```bash
4555
git clone https://github.com/cloud-py-api/nc-mcp-server.git
@@ -90,6 +100,17 @@ Add to your `claude_desktop_config.json`:
90100
}
91101
```
92102

103+
### With Claude Code
104+
105+
```bash
106+
claude mcp add nextcloud \
107+
-e NEXTCLOUD_URL=https://your-nextcloud.example.com \
108+
-e NEXTCLOUD_USER=your-username \
109+
-e NEXTCLOUD_PASSWORD=your-app-password \
110+
-e NEXTCLOUD_MCP_PERMISSIONS=read \
111+
-- nextcloud-mcp
112+
```
113+
93114
### As HTTP Server (for containers/remote)
94115

95116
```bash
@@ -106,34 +127,80 @@ nextcloud-mcp
106127

107128
## Available Tools
108129

109-
### Files (Phase 1 — available now)
130+
### Files
110131

111132
| Tool | Permission | Description |
112133
|------|-----------|-------------|
113134
| `list_directory(path)` | read | List files and folders |
114135
| `get_file(path)` | read | Read a file's content |
136+
| `search_files(name, mime_type, ...)` | read | Search files by name, type, or path |
115137
| `upload_file(path, content)` | write | Upload or overwrite a file |
116138
| `create_directory(path)` | write | Create a new directory |
117139
| `delete_file(path)` | destructive | Delete a file or directory |
118140
| `move_file(source, destination)` | destructive | Move or rename a file |
119141

120-
### Users (Phase 1 — available now)
142+
### Users
121143

122144
| Tool | Permission | Description |
123145
|------|-----------|-------------|
124146
| `get_current_user()` | read | Get current user info |
125147
| `list_users(search, limit)` | read | List/search users |
126148
| `get_user(user_id)` | read | Get specific user details |
127149

150+
### Notifications
151+
152+
| Tool | Permission | Description |
153+
|------|-----------|-------------|
154+
| `list_notifications()` | read | List all notifications |
155+
| `dismiss_notification(id)` | write | Dismiss a single notification |
156+
| `dismiss_all_notifications()` | write | Dismiss all notifications |
157+
158+
### Activity
159+
160+
| Tool | Permission | Description |
161+
|------|-----------|-------------|
162+
| `get_activity(filter, sort, limit, since)` | read | View recent activity with filtering and pagination |
163+
164+
### Talk
165+
166+
| Tool | Permission | Description |
167+
|------|-----------|-------------|
168+
| `list_conversations()` | read | List all Talk conversations |
169+
| `get_conversation(token)` | read | Get conversation details |
170+
| `get_messages(token, ...)` | read | Get messages from a conversation |
171+
| `get_participants(token)` | read | List participants in a conversation |
172+
| `send_message(token, message)` | write | Send a message to a conversation |
173+
| `create_conversation(name, ...)` | write | Create a new conversation |
174+
| `delete_message(token, id)` | destructive | Delete a message |
175+
| `leave_conversation(token)` | destructive | Leave a conversation |
176+
177+
### Talk Polls
178+
179+
| Tool | Permission | Description |
180+
|------|-----------|-------------|
181+
| `get_poll(token, poll_id)` | read | Get poll details and results |
182+
| `create_poll(token, question, options)` | write | Create a poll in a conversation |
183+
| `vote_poll(token, poll_id, options)` | write | Vote on a poll |
184+
| `close_poll(token, poll_id)` | write | Close a poll |
185+
186+
### Comments
187+
188+
| Tool | Permission | Description |
189+
|------|-----------|-------------|
190+
| `list_comments(path, ...)` | read | List comments on a file |
191+
| `add_comment(path, message)` | write | Add a comment to a file |
192+
| `edit_comment(path, comment_id, message)` | write | Edit a comment |
193+
| `delete_comment(path, comment_id)` | destructive | Delete a comment |
194+
128195
### Coming Soon
129196

130-
- **Notifications** — list and dismiss
131-
- **Activity** — recent activity feed
132-
- **Talk** — conversations and messages
133197
- **Shares** — manage file shares
198+
- **Trashbin** — view and restore deleted files
199+
- **File Versions** — list and restore file versions
134200
- **Calendar** — events via CalDAV
135201
- **Contacts** — contacts via CardDAV
136202
- **Deck** — boards and cards
203+
- **Notes** — manage notes
137204

138205
## Development
139206

@@ -164,7 +231,7 @@ export NEXTCLOUD_PASSWORD=admin
164231
pytest tests/integration/ -v -m integration
165232
```
166233

167-
CI automatically runs integration tests against a fresh Nextcloud Docker container.
234+
CI automatically runs integration tests against Nextcloud 32 and 33 Docker containers.
168235

169236
## About This Project
170237

pyproject.toml

Lines changed: 10 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -51,32 +51,36 @@ lint.select = [
5151
"A",
5252
"ASYNC",
5353
"B",
54+
"BLE",
5455
"C",
55-
"C4",
5656
"DTZ",
5757
"E",
5858
"ERA",
5959
"F",
60+
"FLY",
6061
"FURB",
6162
"G",
6263
"I",
64+
"ISC",
6365
"LOG",
66+
"N",
6467
"PERF",
68+
"PGH",
6569
"PIE",
66-
"PLC",
67-
"PLE",
68-
"PLR",
69-
"PLW",
70+
"PL",
7071
"PT",
7172
"Q",
7273
"RET",
7374
"RSE",
7475
"RUF",
7576
"S",
7677
"SIM",
78+
"T10",
7779
"T20",
80+
"TRY",
7881
"UP",
7982
"W",
83+
"YTT",
8084
]
8185
lint.extend-ignore = [
8286
"I001",
@@ -86,6 +90,7 @@ lint.extend-ignore = [
8690
"S311",
8791
"S603",
8892
"SIM117",
93+
"TRY003",
8994
]
9095
lint.extend-per-file-ignores."src/nextcloud_mcp/client.py" = [ "S314" ]
9196
lint.extend-per-file-ignores."src/nextcloud_mcp/config.py" = [ "S104" ]

0 commit comments

Comments
 (0)