nextcloud-agent 0.1.1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Knuckles Team
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,445 @@
1
+ Metadata-Version: 2.4
2
+ Name: nextcloud-agent
3
+ Version: 0.1.1
4
+ Summary: Nextcloud MCP Server for Agentic AI!
5
+ Author-email: Audel Rouhi <knucklessg1@gmail.com>
6
+ License: MIT
7
+ Classifier: Development Status :: 3 - Alpha
8
+ Classifier: License :: OSI Approved :: MIT License
9
+ Classifier: Environment :: Console
10
+ Classifier: Operating System :: POSIX :: Linux
11
+ Classifier: Programming Language :: Python :: 3
12
+ Requires-Python: >=3.10
13
+ Description-Content-Type: text/markdown
14
+ License-File: LICENSE
15
+ Requires-Dist: requests>=2.31.0
16
+ Requires-Dist: urllib3>=2.2.2
17
+ Requires-Dist: python-dateutil>=2.8.2
18
+ Requires-Dist: icalendar>=6.1.1
19
+ Requires-Dist: vobject>=0.9.9
20
+ Requires-Dist: fastmcp>=3.0.0b1
21
+ Requires-Dist: eunomia-mcp>=0.3.10
22
+ Requires-Dist: pydantic-ai-slim[a2a,ag-ui,anthropic,fastmcp,google,huggingface,openai,web]>=1.32.0
23
+ Requires-Dist: pydantic-ai-skills
24
+ Requires-Dist: fastapi>=0.128.0
25
+ Dynamic: license-file
26
+
27
+ # Nextcloud - A2A | AG-UI | MCP
28
+
29
+ ![PyPI - Version](https://img.shields.io/pypi/v/nextcloud-agent)
30
+ ![MCP Server](https://badge.mcpx.dev?type=server 'MCP Server')
31
+ ![PyPI - Downloads](https://img.shields.io/pypi/dd/nextcloud-agent)
32
+ ![GitHub Repo stars](https://img.shields.io/github/stars/Knuckles-Team/nextcloud-agent)
33
+ ![GitHub forks](https://img.shields.io/github/forks/Knuckles-Team/nextcloud-agent)
34
+ ![GitHub contributors](https://img.shields.io/github/contributors/Knuckles-Team/nextcloud-agent)
35
+ ![PyPI - License](https://img.shields.io/pypi/l/nextcloud-agent)
36
+ ![GitHub](https://img.shields.io/github/license/Knuckles-Team/nextcloud-agent)
37
+
38
+ ![GitHub last commit (by committer)](https://img.shields.io/github/last-commit/Knuckles-Team/nextcloud-agent)
39
+ ![GitHub pull requests](https://img.shields.io/github/issues-pr/Knuckles-Team/nextcloud-agent)
40
+ ![GitHub closed pull requests](https://img.shields.io/github/issues-pr-closed/Knuckles-Team/nextcloud-agent)
41
+ ![GitHub issues](https://img.shields.io/github/issues/Knuckles-Team/nextcloud-agent)
42
+
43
+ ![GitHub top language](https://img.shields.io/github/languages/top/Knuckles-Team/nextcloud-agent)
44
+ ![GitHub language count](https://img.shields.io/github/languages/count/Knuckles-Team/nextcloud-agent)
45
+ ![GitHub repo size](https://img.shields.io/github/repo-size/Knuckles-Team/nextcloud-agent)
46
+ ![GitHub repo file count (file type)](https://img.shields.io/github/directory-file-count/Knuckles-Team/nextcloud-agent)
47
+ ![PyPI - Wheel](https://img.shields.io/pypi/wheel/nextcloud-agent)
48
+ ![PyPI - Implementation](https://img.shields.io/pypi/implementation/nextcloud-agent)
49
+
50
+ *Version: 0.1.1*
51
+
52
+ ## Overview
53
+
54
+ Nextcloud MCP Server + A2A Server
55
+
56
+ It includes a Model Context Protocol (MCP) server and an out of the box Agent2Agent (A2A) agent
57
+
58
+ Interacts with your self-hosted Nextcloud instance to manage files, calendars, contacts, and sharing through an MCP server!
59
+
60
+ This repository is actively maintained - Contributions are welcome!
61
+
62
+ ### Supports:
63
+ - **File Operations**: List, Read, Write, Move, Copy, Delete, Create Folder, Get Properties
64
+ - **Sharing**: List Shares, Create Share, Delete Share
65
+ - **Calendars**: List Calendars, List Events, Create Event
66
+ - **Contacts**: List Address Books, List Contacts, Create Contact
67
+ - **User Info**: Get current user details
68
+
69
+ ## MCP
70
+
71
+ ### MCP Tools
72
+
73
+ | Function Name | Description | Tag(s) |
74
+ |:---|:---|:---|
75
+ | `list_files` | List files and directories at a specific path. | `files` |
76
+ | `read_file` | Read the contents of a text file. | `files` |
77
+ | `write_file` | Write text content to a file. | `files` |
78
+ | `create_folder` | Create a new directory. | `files` |
79
+ | `delete_item` | Delete a file or directory. | `files` |
80
+ | `move_item` | Move a file or directory. | `files` |
81
+ | `copy_item` | Copy a file or directory. | `files` |
82
+ | `get_properties` | Get detailed properties for a file or folder. | `files` |
83
+ | `list_shares` | List all shares. | `sharing` |
84
+ | `create_share` | Create a new share (User, Group, Link, Email). | `sharing` |
85
+ | `delete_share` | Delete a share. | `sharing` |
86
+ | `list_calendars` | List available calendars. | `calendar` |
87
+ | `list_calendar_events` | List events in a calendar. | `calendar` |
88
+ | `create_calendar_event` | Create a calendar event. | `calendar` |
89
+ | `list_address_books` | List address books. | `contacts` |
90
+ | `list_contacts` | List contacts in an address book. | `contacts` |
91
+ | `create_contact` | Create a new contact. | `contacts` |
92
+ | `get_user_info` | Get information about the current user. | `user` |
93
+
94
+
95
+ ### Using as an MCP Server
96
+
97
+ The MCP Server can be run in two modes: `stdio` (for local testing) or `http` (for networked access). To start the server, use the following commands:
98
+
99
+ #### Run in stdio mode (default):
100
+ ```bash
101
+ nextcloud-agent --transport "stdio"
102
+ ```
103
+
104
+ #### Run in HTTP mode:
105
+ ```bash
106
+ nextcloud-agent --transport "http" --host "0.0.0.0" --port "8016"
107
+ ```
108
+
109
+ AI Prompt:
110
+ ```text
111
+ List all files in my 'Documents' folder.
112
+ ```
113
+
114
+ AI Response:
115
+ ```text
116
+ Contents of 'Documents':
117
+ [FILE] Project_Proposal.docx (Size: 15403, Modified: Sun, 01 Feb 2026 10:00:00 GMT)
118
+ [FILE] Notes.txt (Size: 450, Modified: Sun, 01 Feb 2026 09:30:00 GMT)
119
+ [DIR] Financials (Size: -, Modified: Fri, 30 Jan 2026 14:20:00 GMT)
120
+ ```
121
+
122
+ ## A2A Agent
123
+
124
+ This package also includes an A2A agent server that can be used to interact with the Nextcloud MCP server.
125
+
126
+ ### Architecture:
127
+
128
+ ```mermaid
129
+ ---
130
+ config:
131
+ layout: dagre
132
+ ---
133
+ flowchart TB
134
+ subgraph subGraph0["Agent Capabilities"]
135
+ C["Agent"]
136
+ B["A2A Server - Uvicorn/FastAPI"]
137
+ D["MCP Tools"]
138
+ F["Agent Skills"]
139
+ end
140
+ C --> D & F
141
+ A["User Query"] --> B
142
+ B --> C
143
+ D --> E["Nextcloud API"]
144
+
145
+ C:::agent
146
+ B:::server
147
+ A:::server
148
+ classDef server fill:#f9f,stroke:#333
149
+ classDef agent fill:#bbf,stroke:#333,stroke-width:2px
150
+ style B stroke:#000000,fill:#FFD600
151
+ style D stroke:#000000,fill:#BBDEFB
152
+ style F fill:#BBDEFB
153
+ style A fill:#C8E6C9
154
+ style subGraph0 fill:#FFF9C4
155
+ ```
156
+
157
+ ### Component Interaction Diagram
158
+
159
+ ```mermaid
160
+ sequenceDiagram
161
+ participant User
162
+ participant Server as A2A Server
163
+ participant Agent as Agent
164
+ participant Skill as Agent Skills
165
+ participant MCP as MCP Tools
166
+
167
+ User->>Server: Send Query
168
+ Server->>Agent: Invoke Agent
169
+ Agent->>Skill: Analyze Skills Available
170
+ Skill->>Agent: Provide Guidance on Next Steps
171
+ Agent->>MCP: Invoke Tool
172
+ MCP-->>Agent: Tool Response Returned
173
+ Agent-->>Agent: Return Results Summarized
174
+ Agent-->>Server: Final Response
175
+ Server-->>User: Output
176
+ ```
177
+
178
+ ## Usage
179
+
180
+ ### MCP CLI
181
+
182
+ | Short Flag | Long Flag | Description |
183
+ |------------|------------------------------------|-----------------------------------------------------------------------------|
184
+ | -h | --help | Display help information |
185
+ | -t | --transport | Transport method: 'stdio', 'http', or 'sse' [legacy] (default: stdio) |
186
+ | -s | --host | Host address for HTTP transport (default: 0.0.0.0) |
187
+ | -p | --port | Port number for HTTP transport (default: 8016) |
188
+ | | --auth-type | Authentication type: 'none', 'static', 'jwt', 'oauth-proxy', 'oidc-proxy', 'remote-oauth' (default: none) |
189
+ | | --token-jwks-uri | JWKS URI for JWT verification |
190
+ | | --token-issuer | Issuer for JWT verification |
191
+ | | --token-audience | Audience for JWT verification |
192
+ | | --oauth-upstream-auth-endpoint | Upstream authorization endpoint for OAuth Proxy |
193
+ | | --oauth-upstream-token-endpoint | Upstream token endpoint for OAuth Proxy |
194
+ | | --oauth-upstream-client-id | Upstream client ID for OAuth Proxy |
195
+ | | --oauth-upstream-client-secret | Upstream client secret for OAuth Proxy |
196
+ | | --oauth-base-url | Base URL for OAuth Proxy |
197
+ | | --oidc-config-url | OIDC configuration URL |
198
+ | | --oidc-client-id | OIDC client ID |
199
+ | | --oidc-client-secret | OIDC client secret |
200
+ | | --oidc-base-url | Base URL for OIDC Proxy |
201
+ | | --remote-auth-servers | Comma-separated list of authorization servers for Remote OAuth |
202
+ | | --remote-base-url | Base URL for Remote OAuth |
203
+ | | --allowed-client-redirect-uris | Comma-separated list of allowed client redirect URIs |
204
+ | | --eunomia-type | Eunomia authorization type: 'none', 'embedded', 'remote' (default: none) |
205
+ | | --eunomia-policy-file | Policy file for embedded Eunomia (default: mcp_policies.json) |
206
+ | | --eunomia-remote-url | URL for remote Eunomia server |
207
+
208
+
209
+ ### A2A CLI
210
+ #### Endpoints
211
+ - **Web UI**: `http://localhost:9016/` (if enabled)
212
+ - **A2A**: `http://localhost:9016/a2a` (Discovery: `/a2a/.well-known/agent.json`)
213
+ - **AG-UI**: `http://localhost:9016/ag-ui` (POST)
214
+
215
+ | Short Flag | Long Flag | Description |
216
+ |------------|-------------------|------------------------------------------------------------------------|
217
+ | -h | --help | Display help information |
218
+ | | --host | Host to bind the server to (default: 0.0.0.0) |
219
+ | | --port | Port to bind the server to (default: 9016) |
220
+ | | --reload | Enable auto-reload |
221
+ | | --provider | LLM Provider: 'openai', 'anthropic', 'google', 'huggingface' |
222
+ | | --model-id | LLM Model ID (default: qwen/qwen3-4b-2507) |
223
+ | | --base-url | LLM Base URL (for OpenAI compatible providers) |
224
+ | | --api-key | LLM API Key |
225
+ | | --mcp-url | MCP Server URL (default: http://localhost:8016/mcp) |
226
+ | | --web | Enable Pydantic AI Web UI | False (Env: ENABLE_WEB_UI) |
227
+
228
+
229
+ ### Using as an MCP Server
230
+ The MCP Server can be run in two modes: `stdio` (for local testing) or `http` (for networked access). To start the server, use the following commands:
231
+
232
+ #### Run in stdio mode (default):
233
+ ```bash
234
+ nextcloud-agent --transport "stdio"
235
+ ```
236
+
237
+ #### Run in HTTP mode:
238
+ ```bash
239
+ nextcloud-agent --transport "http" --host "0.0.0.0" --port "8016"
240
+ ```
241
+
242
+ AI Prompt:
243
+ ```text
244
+ List all files in my 'Documents' folder.
245
+ ```
246
+
247
+ AI Response:
248
+ ```text
249
+ Contents of 'Documents':
250
+ [FILE] Project_Proposal.docx (Size: 15403, Modified: Sun, 01 Feb 2026 10:00:00 GMT)
251
+ [FILE] Notes.txt (Size: 450, Modified: Sun, 01 Feb 2026 09:30:00 GMT)
252
+ [DIR] Financials (Size: -, Modified: Fri, 30 Jan 2026 14:20:00 GMT)
253
+ ```
254
+
255
+ ### Agentic AI
256
+ `nextcloud-agent` is designed to be used by Agentic AI systems. It provides a set of tools that allow agents to manage Nextcloud resources.
257
+
258
+ ## Agent-to-Agent (A2A)
259
+
260
+ This package also includes an A2A agent server that can be used to interact with the Nextcloud MCP server.
261
+
262
+ ### CLI
263
+
264
+ | Argument | Description | Default |
265
+ |-------------------|----------------------------------------------------------------|--------------------------------|
266
+ | `--host` | Host to bind the server to | `0.0.0.0` |
267
+ | `--port` | Port to bind the server to | `9016` |
268
+ | `--reload` | Enable auto-reload | `False` |
269
+ | `--provider` | LLM Provider (openai, anthropic, google, huggingface) | `openai` |
270
+ | `--model-id` | LLM Model ID | `qwen/qwen3-4b-2507` |
271
+ | `--base-url` | LLM Base URL (for OpenAI compatible providers) | `http://ollama.arpa/v1` |
272
+ | `--api-key` | LLM API Key | `ollama` |
273
+ | `--mcp-url` | MCP Server URL | `http://nextcloud-mcp:8016/mcp` |
274
+ | `--allowed-tools` | List of allowed MCP tools | `list_files`, `...` |
275
+
276
+ ### Examples
277
+
278
+ #### Run A2A Server
279
+ ```bash
280
+ nextcloud-agent --provider openai --model-id gpt-4 --api-key sk-... --mcp-url http://localhost:8016/mcp
281
+ ```
282
+
283
+ #### Run with Docker
284
+ ```bash
285
+ docker run -e CMD=nextcloud-agent -p 9016:9016 nextcloud-agent
286
+ ```
287
+
288
+ ## Docker
289
+
290
+ ### Build
291
+
292
+ ```bash
293
+ docker build -t nextcloud-agent .
294
+ ```
295
+
296
+ ### Run MCP Server
297
+
298
+ ```bash
299
+ docker run -p 8016:8016 nextcloud-agent
300
+ ```
301
+
302
+ ### Run A2A Server
303
+
304
+ ```bash
305
+ docker run -e CMD=nextcloud-agent -p 9016:9016 nextcloud-agent
306
+ ```
307
+
308
+ ### Deploy MCP Server as a Service
309
+
310
+ The Nextcloud MCP server can be deployed using Docker, with configurable authentication, middleware, and Eunomia authorization.
311
+
312
+ #### Using Docker Run
313
+
314
+ ```bash
315
+ docker pull knucklessg1/nextcloud-agent:latest
316
+
317
+ docker run -d \
318
+ --name nextcloud-agent \
319
+ -p 8016:8016 \
320
+ -e HOST=0.0.0.0 \
321
+ -e PORT=8016 \
322
+ -e TRANSPORT=http \
323
+ -e AUTH_TYPE=none \
324
+ -e EUNOMIA_TYPE=none \
325
+ -e NEXTCLOUD_BASE_URL=https://cloud.example.com \
326
+ -e NEXTCLOUD_USERNAME=user \
327
+ -e NEXTCLOUD_PASSWORD=pass \
328
+ knucklessg1/nextcloud-agent:latest
329
+ ```
330
+
331
+ For advanced authentication (e.g., JWT, OAuth Proxy, OIDC Proxy, Remote OAuth) or Eunomia, add the relevant environment variables:
332
+
333
+ ```bash
334
+ docker run -d \
335
+ --name nextcloud-agent \
336
+ -p 8016:8016 \
337
+ -e HOST=0.0.0.0 \
338
+ -e PORT=8016 \
339
+ -e TRANSPORT=http \
340
+ -e AUTH_TYPE=oidc-proxy \
341
+ -e OIDC_CONFIG_URL=https://provider.com/.well-known/openid-configuration \
342
+ -e OIDC_CLIENT_ID=your-client-id \
343
+ -e OIDC_CLIENT_SECRET=your-client-secret \
344
+ -e OIDC_BASE_URL=https://your-server.com \
345
+ -e ALLOWED_CLIENT_REDIRECT_URIS=http://localhost:*,https://*.example.com/* \
346
+ -e EUNOMIA_TYPE=embedded \
347
+ -e EUNOMIA_POLICY_FILE=/app/mcp_policies.json \
348
+ -e NEXTCLOUD_BASE_URL=https://cloud.example.com \
349
+ -e NEXTCLOUD_USERNAME=user \
350
+ -e NEXTCLOUD_PASSWORD=pass \
351
+ knucklessg1/nextcloud-agent:latest
352
+ ```
353
+
354
+ #### Using Docker Compose
355
+
356
+ Create a `docker-compose.yml` file:
357
+
358
+ ```yaml
359
+ services:
360
+ nextcloud-mcp:
361
+ image: knucklessg1/nextcloud-agent:latest
362
+ environment:
363
+ - HOST=0.0.0.0
364
+ - PORT=8016
365
+ - TRANSPORT=http
366
+ - AUTH_TYPE=none
367
+ - EUNOMIA_TYPE=none
368
+ - NEXTCLOUD_BASE_URL=https://cloud.example.com
369
+ - NEXTCLOUD_USERNAME=user
370
+ - NEXTCLOUD_PASSWORD=pass
371
+ ports:
372
+ - 8016:8016
373
+ ```
374
+
375
+ For advanced setups with authentication and Eunomia:
376
+
377
+ ```yaml
378
+ services:
379
+ nextcloud-mcp:
380
+ image: knucklessg1/nextcloud-agent:latest
381
+ environment:
382
+ - HOST=0.0.0.0
383
+ - PORT=8016
384
+ - TRANSPORT=http
385
+ - AUTH_TYPE=oidc-proxy
386
+ - OIDC_CONFIG_URL=https://provider.com/.well-known/openid-configuration
387
+ - OIDC_CLIENT_ID=your-client-id
388
+ - OIDC_CLIENT_SECRET=your-client-secret
389
+ - OIDC_BASE_URL=https://your-server.com
390
+ - ALLOWED_CLIENT_REDIRECT_URIS=http://localhost:*,https://*.example.com/*
391
+ - EUNOMIA_TYPE=embedded
392
+ - EUNOMIA_POLICY_FILE=/app/mcp_policies.json
393
+ - NEXTCLOUD_BASE_URL=https://cloud.example.com
394
+ - NEXTCLOUD_USERNAME=user
395
+ - NEXTCLOUD_PASSWORD=pass
396
+ ports:
397
+ - 8016:8016
398
+ volumes:
399
+ - ./mcp_policies.json:/app/mcp_policies.json
400
+ ```
401
+
402
+ Run the service:
403
+
404
+ ```bash
405
+ docker-compose up -d
406
+ ```
407
+
408
+ #### Configure `mcp.json` for AI Integration
409
+
410
+ ```json
411
+ {
412
+ "mcpServers": {
413
+ "nextcloud": {
414
+ "command": "uv",
415
+ "args": [
416
+ "run",
417
+ "--with",
418
+ "nextcloud-agent"
419
+ ],
420
+ "env": {
421
+ "NEXTCLOUD_BASE_URL": "https://cloud.example.com",
422
+ "NEXTCLOUD_USERNAME": "user",
423
+ "NEXTCLOUD_PASSWORD": "pass"
424
+ },
425
+ "timeout": 300000
426
+ }
427
+ }
428
+ }
429
+ ```
430
+
431
+ ## Install Python Package
432
+
433
+ ```bash
434
+ python -m pip install nextcloud-agent
435
+ ```
436
+ ```bash
437
+ uv pip install nextcloud-agent
438
+ ```
439
+
440
+ ## Repository Owners
441
+
442
+ <img width="100%" height="180em" src="https://github-readme-stats.vercel.app/api?username=Knucklessg1&show_icons=true&hide_border=true&&count_private=true&include_all_commits=true" />
443
+
444
+ ![GitHub followers](https://img.shields.io/github/followers/Knucklessg1)
445
+ ![GitHub User's stars](https://img.shields.io/github/stars/Knucklessg1)