Nextcloud-A2A · AG-UI · MCP
版本:0.11.0
概述
Nextcloud MCP服务器+A2A服务器
它包括一个模型上下文协议(MCP)服务器和一个现成的Agent2Agent(A2A)代理
与您的自托管Nextcloud实例交互,通过MCP服务器管理文件、日历、联系人和共享!
此存储库正在积极维护中-欢迎投稿!
支持:
- 文件操作:列表、读取、写入、移动、复制、删除、创建文件夹、获取属性
- 共享:列出共享、创建共享、删除共享
- 日历:列出日历、列出事件、创建事件
- 联系人:列出通讯簿、列出联系人、创建联系人
- 用户信息:获取当前用户详细信息
主控程序
MCP工具
| 函数名称 | 描述 | 标签 |
|---|---|---|
list_files |
列出特定路径下的文件和目录。 | files |
read_file |
读取文本文件的内容。 | files |
write_file |
将文本内容写入文件。 | files |
create_folder |
创建一个新目录。 | files |
delete_item |
删除文件或目录。 | files |
move_item |
移动文件或目录。 | files |
copy_item |
复制文件或目录。 | files |
get_properties |
获取文件或文件夹的详细属性。 | files |
list_shares |
列出所有股份。 | sharing |
create_share |
创建新共享(用户、组、链接、电子邮件)。 | sharing |
delete_share |
删除共享。 | sharing |
list_calendars |
列出可用日历。 | calendar |
list_calendar_events |
在日历中列出事件。 | calendar |
create_calendar_event |
创建日历事件。 | calendar |
list_address_books |
列出地址簿。 | contacts |
list_contacts |
在通讯簿中列出联系人。 | contacts |
create_contact |
创建新联系人。 | contacts |
get_user_info |
获取当前用户的信息。 | user |
用作MCP服务器
MCP服务器可以在两种模式下运行: stdio (用于本地测试)或 http (用于网络访问)。要启动服务器,请使用以下命令:
在stdio模式下运行(默认):```bash
nextcloud-agent --transport "stdio"
#### 在HTTP模式下运行:```bash
nextcloud-agent --transport "http" --host "0.0.0.0" --port "8016"
AI提示:```text
List all files in my 'Documents' folder.
AI回应:```text
Contents of 'Documents':
[FILE] Project_Proposal.docx (Size: 15403, Modified: Sun, 01 Feb 2026 10:00:00 GMT)
[FILE] Notes.txt (Size: 450, Modified: Sun, 01 Feb 2026 09:30:00 GMT)
[DIR] Financials (Size: -, Modified: Fri, 30 Jan 2026 14:20:00 GMT)
A2A代理
此软件包还包括一个A2A代理服务器,可用于与Nextcloud MCP服务器交互。
架构:```mermaid
config:
layout: dagre
flowchart TB
subgraph subGraph0["Agent Capabilities"]
C["Agent"]
B["A2A Server - Uvicorn/FastAPI"]
D["MCP Tools"]
F["Agent Skills"]
end
C --> D & F
A["User Query"] --> B
B --> C
D --> E["Nextcloud API"]
C:::agent
B:::server
A:::server
classDef server fill:#f9f,stroke:#333
classDef agent fill:#bbf,stroke:#333,stroke-width:2px
style B stroke:#000000,fill:#FFD600
style D stroke:#000000,fill:#BBDEFB
style F fill:#BBDEFB
style A fill:#C8E6C9
style subGraph0 fill:#FFF9C4
### 组件交互图```mermaid
sequenceDiagram
participant User
participant Server as A2A Server
participant Agent as Agent
participant Skill as Agent Skills
participant MCP as MCP Tools
User->>Server: Send Query
Server->>Agent: Invoke Agent
Agent->>Skill: Analyze Skills Available
Skill->>Agent: Provide Guidance on Next Steps
Agent->>MCP: Invoke Tool
MCP-->>Agent: Tool Response Returned
Agent-->>Agent: Return Results Summarized
Agent-->>Server: Final Response
Server-->>User: Output
图形架构
此代理使用 pydantic-graph 智能路由和最佳上下文管理的编排。```mermaid
title: Nextcloud Agent Graph Agent
stateDiagram-v2
[] --> RouterNode: User Query
RouterNode --> DomainNode: Classified Domain
RouterNode --> []: Low confidence / Error
DomainNode --> [*]: Domain Result
- **路由器节点**:快速、轻便的LLM(例如。, `nvidia/nemotron-3-super`)它将用户的查询分类到一个专门的域中。
- **域节点**:执行器节点。对于所选域,它动态设置环境变量,以暂时仅启用与该域相关的工具,从而创建高度集中的子代理(例如。, `gpt-4o`)以完成请求。这保留了LLM上下文并防止了工具幻觉。
## 用法
### MCP-CLI
|短旗|长旗|描述|
|------------|------------------------------------|-----------------------------------------------------------------------------|
|-h|--help|显示帮助信息|
|-t |--transport |传输方法:“stdio”、“http”或“sse”\遗留\|
|-s|--host|HTTP传输的主机地址(默认值:0.0.0.0)|
|-p|--port|HTTP传输的端口号(默认值:8016)|
||--auth-type|身份验证类型:“none”、“static”、“jwt”、“oauth代理”、“oidc代理”和“remote oauth”(默认值:none)|
||--令牌jwks-uri |用于JWT验证的jwks uri|
||--代币发行人| JWT验证发行人|
||--令牌受众|JWT验证的受众|
||--oauth上游授权端点|oauth代理的上游授权端点|
||--oauth上游令牌端点|oauth代理的上游令牌端点|
||--oauth上游客户端id | oauth代理的上游客户端id|
||--oauth上游客户端机密|oauth代理的上游客户端机密|
||--oauth基本url | oauth代理的基本url|
||--oidc配置url |oidc配置url|
||--oidc客户端id|oidc客户端id|
||-oidc客户端机密|oidc客户端机密|
||--oidc基本url |oidc代理的基本url|
||--远程身份验证服务器|远程OAuth的逗号分隔的授权服务器列表|
||--远程基本url |远程OAuth的基本url|
||--允许的客户端重定向URI |逗号分隔的允许客户端重定向URI列表|
||--eunomia type|eunomia授权类型:“无”、“嵌入式”、“远程”(默认值:无)|
||--eunomia策略文件|嵌入式eunomia的策略文件(默认:mcp_policies.json)|
||--eunomia远程url|远程eunomia服务器的url|
### A2A-CLI
#### 端点
- **Web 用户界面**: `http://localhost:9016/` (如果启用)
- **A2A**: `http://localhost:9016/a2a` (发现: `/a2a/.well-known/agent.json`)
- **AG-UI**: `http://localhost:9016/ag-ui` (职位)
短旗 · 长旗 · 描述
-h · --help · 显示帮助信息
--host · 绑定服务器的主机(默认值:0.0.0.0)
--port · 绑定服务器的端口(默认:9016)
--reload · 启用自动重新加载
--provider · LLM提供者:“openai”、“anthropic”、“google”、“huggingface”
--型号id · LLM型号id(默认:nvidia/nemotron-3-super)
--基本url · LLM基本url(适用于OpenAI兼容的提供者)
--api-key · LLM api密钥
--mcp url · mcp服务器url(默认值:http://localhost:8016/mcp)
--web · 启用Pydantic AI web UI · False(环境:Enable_web_UI)
### 用作MCP服务器
MCP服务器可以在两种模式下运行: `stdio` (用于本地测试)或 `http` (用于网络访问)。要启动服务器,请使用以下命令:
#### 在stdio模式下运行(默认):```bash
nextcloud-agent --transport "stdio"
在HTTP模式下运行:```bash
nextcloud-agent --transport "http" --host "0.0.0.0" --port "8016"
AI提示:```text
List all files in my 'Documents' folder.
AI回应:```text
Contents of 'Documents':
[FILE] Project_Proposal.docx (Size: 15403, Modified: Sun, 01 Feb 2026 10:00:00 GMT)
[FILE] Notes.txt (Size: 450, Modified: Sun, 01 Feb 2026 09:30:00 GMT)
[DIR] Financials (Size: -, Modified: Fri, 30 Jan 2026 14:20:00 GMT)
### AI 代理
`nextcloud-agent` 设计用于Agent AI系统。它提供了一组工具,允许代理管理Nextcloud资源。
## 代理人对代理人(A2A)
此软件包还包括一个A2A代理服务器,可用于与Nextcloud MCP服务器交互。
### 命令行界面
|参数|描述|默认值|
|-------------------|----------------------------------------------------------------|--------------------------------|
| `--host` |将服务器绑定到的主机| `0.0.0.0` |
| `--port` |将服务器绑定到的端口| `9016` |
| `--reload` |启用自动重新加载| `False` |
| `--provider` |法学硕士提供者(openai、anthropic、谷歌、hugginface)| `openai` |
| `--model-id` |LLM型号ID| `nvidia/nemotron-3-super` |
| `--base-url` |LLM基本URL(适用于OpenAI兼容提供商)| `http://ollama.arpa/v1` |
| `--api-key` |LLM API密钥| `ollama` |
| `--mcp-url` |MCP服务器URL| `http://nextcloud-mcp:8016/mcp` |
| `--allowed-tools` |允许的MCP工具列表| `list_files`, `...` |
### 示例
#### 运行A2A服务器```bash
nextcloud-agent --provider openai --model-id gpt-4 --api-key sk-... --mcp-url http://localhost:8016/mcp
使用Docker运行```bash
docker run -e CMD=nextcloud-agent -p 9016:9016 nextcloud-agent
## 码头工人
### 构建```bash
docker build -t nextcloud-agent .
运行MCP服务器```bash
docker run -p 8016:8016 nextcloud-agent
### 运行A2A服务器```bash
docker run -e CMD=nextcloud-agent -p 9016:9016 nextcloud-agent
将MCP服务器部署为服务
Nextcloud MCP服务器可以使用Docker部署,具有可配置的身份验证、中间件和Eunomia授权。
使用Docker运行```bash
docker pull knucklessg1/nextcloud-agent:latest
docker run -d \
--name nextcloud-agent \
-p 8016:8016 \
-e HOST=0.0.0.0 \
-e PORT=8016 \
-e TRANSPORT=http \
-e AUTH_TYPE=none \
-e EUNOMIA_TYPE=none \
-e NEXTCLOUD_BASE_URL=https://cloud.example.com \
-e NEXTCLOUD_USERNAME=user \
-e NEXTCLOUD_PASSWORD=pass \
knucklessg1/nextcloud-agent:latest
对于高级身份验证(例如JWT、OAuth代理、OIDC代理、远程OAuth)或Eunomia,添加相关的环境变量:```bash
docker run -d \
--name nextcloud-agent \
-p 8016:8016 \
-e HOST=0.0.0.0 \
-e PORT=8016 \
-e TRANSPORT=http \
-e AUTH_TYPE=oidc-proxy \
-e OIDC_CONFIG_URL=https://provider.com/.well-known/openid-configuration \
-e OIDC_CLIENT_ID=your-client-id \
-e OIDC_CLIENT_SECRET=your-client-secret \
-e OIDC_BASE_URL=https://your-server.com \
-e ALLOWED_CLIENT_REDIRECT_URIS=http://localhost:*,https://*.example.com/* \
-e EUNOMIA_TYPE=embedded \
-e EUNOMIA_POLICY_FILE=/app/mcp_policies.json \
-e NEXTCLOUD_BASE_URL=https://cloud.example.com \
-e NEXTCLOUD_USERNAME=user \
-e NEXTCLOUD_PASSWORD=pass \
knucklessg1/nextcloud-agent:latest
使用Docker Compose
创建一个 docker-compose.yml 文件:```yaml
services:
nextcloud-mcp:
image: knucklessg1/nextcloud-agent:latest
environment:
- HOST=0.0.0.0
- PORT=8016
- TRANSPORT=http
- AUTH_TYPE=none
- EUNOMIA_TYPE=none
- NEXTCLOUD_BASE_URL=https://cloud.example.com
- NEXTCLOUD_USERNAME=user
- NEXTCLOUD_PASSWORD=pass
ports:
- 8016:8016
对于具有身份验证和Eunomia的高级设置:```yaml
services:
nextcloud-mcp:
image: knucklessg1/nextcloud-agent:latest
environment:
- HOST=0.0.0.0
- PORT=8016
- TRANSPORT=http
- AUTH_TYPE=oidc-proxy
- OIDC_CONFIG_URL=https://provider.com/.well-known/openid-configuration
- OIDC_CLIENT_ID=your-client-id
- OIDC_CLIENT_SECRET=your-client-secret
- OIDC_BASE_URL=https://your-server.com
- ALLOWED_CLIENT_REDIRECT_URIS=http://localhost:*,https://*.example.com/*
- EUNOMIA_TYPE=embedded
- EUNOMIA_POLICY_FILE=/app/mcp_policies.json
- NEXTCLOUD_BASE_URL=https://cloud.example.com
- NEXTCLOUD_USERNAME=user
- NEXTCLOUD_PASSWORD=pass
ports:
- 8016:8016
volumes:
- ./mcp_policies.json:/app/mcp_policies.json
运行服务:```bash
docker-compose up -d
#### 配置 `mcp.json` AI集成```json
{
"mcpServers": {
"nextcloud": {
"command": "uv",
"args": [
"run",
"--with",
"nextcloud-agent"
],
"env": {
"NEXTCLOUD_BASE_URL": "https://cloud.example.com",
"NEXTCLOUD_USERNAME": "user",
"NEXTCLOUD_PASSWORD": "pass"
},
"timeout": 300000
}
}
}
安装Python包```bash
python -m pip install nextcloud-agent
``````bash
uv pip install nextcloud-agent
## 存储库所有者
## MCP配置示例
### 1.标准IO(stdio)部署```json
{
"mcpServers": {
"nextcloud-agent": {
"command": "uv",
"args": [
"run",
"nextcloud-mcp"
],
"env": {
"AGENT_DESCRIPTION": "",
"AGENT_SYSTEM_PROMPT": "",
"CALENDARTOOL": "True",
"CONTACTSTOOL": "True",
"DEFAULT_AGENT_NAME": "",
"FILESTOOL": "True",
"MISCTOOL": "True",
"NEXTCLOUD_PASSWORD": "",
"NEXTCLOUD_SSL_VERIFY": "",
"NEXTCLOUD_URL": "",
"NEXTCLOUD_USERNAME": "",
"SHARINGTOOL": "True",
"USERTOOL": "True"
}
}
}
}
2.流式HTTP(SSE)部署```json
{
"mcpServers": {
"nextcloud-agent": {
"command": "uv",
"args": [
"run",
"nextcloud-mcp",
"--transport",
"http",
"--host",
"0.0.0.0",
"--port",
"8000"
],
"env": {
"AGENT_DESCRIPTION": "",
"AGENT_SYSTEM_PROMPT": "",
"CALENDARTOOL": "True",
"CONTACTSTOOL": "True",
"DEFAULT_AGENT_NAME": "",
"FILESTOOL": "True",
"MISCTOOL": "True",
"NEXTCLOUD_PASSWORD": "",
"NEXTCLOUD_SSL_VERIFY": "",
"NEXTCLOUD_URL": "",
"NEXTCLOUD_USERNAME": "",
"SHARINGTOOL": "True",
"USERTOOL": "True"
}
}
}
}
```
