Nextcloud Agent

Nextcloud-A2A|AG-UI|MCP

*版本：0.11.0*

概述

Nextcloud MCP服务器+A2A服务器

它包括一个模型上下文协议（MCP）服务器和一个现成的Agent2Agent（A2A）代理

与您的自托管Nextcloud实例交互，通过MCP服务器管理文件、日历、联系人和共享！

此存储库正在积极维护中-欢迎投稿！

支持：

• 文件操作：列表、读取、写入、移动、复制、删除、创建文件夹、获取属性
• 共享：列出共享、创建共享、删除共享
• 日历：列出日历、列出事件、创建事件
• 联系人：列出通讯簿、列出联系人、创建联系人
• 用户信息：获取当前用户详细信息

主控程序

MCP工具

用作MCP服务器

MCP服务器可以在两种模式下运行： stdio （用于本地测试）或 http （用于网络访问）。要启动服务器，请使用以下命令：

在stdio模式下运行（默认）：

nextcloud-agent --transport "stdio"

在HTTP模式下运行：

nextcloud-agent --transport "http"  --host "0.0.0.0"  --port "8016"

AI提示：

List all files in my 'Documents' folder.

AI回应：

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服务器交互。

架构：

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

组件交互图

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 智能路由和最佳上下文管理的编排。

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

A2A-CLI

端点

• Web 用户界面: http://localhost:9016/ （如果启用）
• A2A: http://localhost:9016/a2a （发现： /a2a/.well-known/agent.json)
• AG-UI: http://localhost:9016/ag-ui （职位）

用作MCP服务器

MCP服务器可以在两种模式下运行： stdio （用于本地测试）或 http （用于网络访问）。要启动服务器，请使用以下命令：

在stdio模式下运行（默认）：

nextcloud-agent --transport "stdio"

在HTTP模式下运行：

nextcloud-agent --transport "http"  --host "0.0.0.0"  --port "8016"

AI提示：

List all files in my 'Documents' folder.

AI回应：

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服务器交互。

命令行界面

示例

运行A2A服务器

nextcloud-agent --provider openai --model-id gpt-4 --api-key sk-... --mcp-url http://localhost:8016/mcp

使用Docker运行

docker run -e CMD=nextcloud-agent -p 9016:9016 nextcloud-agent

码头工人

构建

docker build -t nextcloud-agent .

运行MCP服务器

docker run -p 8016:8016 nextcloud-agent

运行A2A服务器

docker run -e CMD=nextcloud-agent -p 9016:9016 nextcloud-agent

将MCP服务器部署为服务

Nextcloud MCP服务器可以使用Docker部署，具有可配置的身份验证、中间件和Eunomia授权。

使用Docker运行

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，添加相关的环境变量：

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 文件：

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的高级设置：

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

运行服务：

docker-compose up -d

配置 mcp.json AI集成

{
  "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包

python -m pip install nextcloud-agent

uv pip install nextcloud-agent

存储库所有者

MCP配置示例

1.标准IO（stdio）部署

{
  "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）部署

{
  "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"
      }
    }
  }
}