hithereiamaliff-mcp-nextcloud

Nextcloud MCP 服务

MCP 端点： https://mcp.techmavie.digital/nextcloud/mcp

注意： 本项目使用 TypeScript 对原始 Python 版 cbcoutinho/nextcloud-mcp-server 进行了彻底重写，现在支持 自托管 VPS 部署 和 Smithery 部署。

与原始仓库的主要区别：

• 语言： 本项目使用 TypeScript 编写，而原始项目使用 Python。
• Smithery 支持： 新增了对 Smithery 部署以及通过 Smithery playground 进行本地测试的完整支持。
• 项目结构： 项目结构已适配 Node.js/TypeScript 环境，并集成 MCP SDK。
• 依赖项： 本项目使用 npm 进行包管理，而原始项目使用 Python 依赖项管理工具。
• 部署： 现在支持本地开发和通过 Smithery 进行云端部署。

Nextcloud MCP（模型上下文协议）服务可让 OpenAI 的 GPT、Google 的 Gemini 或 Anthropic 的 Claude 等大模型与您的 Nextcloud 实例交互。借助该服务，您可以自动执行各种 Nextcloud 操作，包括 Notes、Calendar、Contacts、Tables 和 WebDAV 文件操作。

托管式 HTTP 集成现在通过 MCP Key Service 支持更安全的多用户流程。托管客户端无需在连接器 URL 中嵌入原始 Nextcloud 凭据，而是可以使用用户专属的 usr_... 密钥，并由服务端解析凭据。

功能

本服务集成了多个 Nextcloud 应用，让大模型能够通过涵盖 5 个主要类别的 30 个工具与您的 Nextcloud 数据交互。

支持的 Nextcloud 应用

应用	支持状态	描述
Notes	✅ 完全支持	创建、读取、更新、删除和搜索笔记，也可向笔记追加内容。
Calendar	✅ 完全支持	完整的日历集成——通过 CalDAV 管理日历和事件。
Tables	✅ 完全支持	完整的表格操作——列出表格、获取架构，以及对行执行 CRUD 操作。
Files (WebDAV)	✅ 完全支持	完整的文件系统访问——浏览目录、读写文件、创建和删除资源。
Contacts	✅ 完全支持	通过 CardDAV 创建、读取、更新和删除联系人及通讯录。

可用工具（共 30 个）

📝 Notes 工具（5 个）

工具	描述
nextcloud_notes_create_note	创建带有标题、内容和类别的新笔记
nextcloud_notes_update_note	根据 ID 更新现有笔记，可选更新标题、内容或类别
nextcloud_notes_append_content	使用清晰的分隔符向现有笔记追加内容
nextcloud_notes_search_notes	按标题或内容搜索笔记，并筛选结果
nextcloud_notes_delete_note	根据 ID 删除笔记

📅 Calendar 工具（6 个）

工具	描述
nextcloud_calendar_list_calendars	列出用户的所有可用日历
nextcloud_calendar_create_event	创建日历事件，可设置摘要、描述、日期和地点
nextcloud_calendar_list_events	列出日历中的事件，可选按日期筛选
nextcloud_calendar_get_event	获取特定事件的详细信息
nextcloud_calendar_update_event	更新现有事件的任意内容
nextcloud_calendar_delete_event	删除日历事件

👥 联系人工具（6 个工具）

工具	描述
nextcloud_contacts_list_addressbooks	列出用户所有可用的通讯录
nextcloud_contacts_create_addressbook	创建通讯录，并设置显示名称和描述
nextcloud_contacts_delete_addressbook	按 ID 删除通讯录
nextcloud_contacts_list_contacts	列出指定通讯录中的所有联系人
nextcloud_contacts_create_contact	创建联系人，并填写全名、电子邮件、电话、地址和组织
nextcloud_contacts_delete_contact	从通讯录中删除联系人

📊 表格工具（6 个工具）

工具	描述
nextcloud_tables_list_tables	列出用户所有可用的表格
nextcloud_tables_get_schema	获取指定表格的架构／结构，包括列
nextcloud_tables_read_table	读取表格中的所有行
nextcloud_tables_insert_row	使用键值数据向表格中插入新行
nextcloud_tables_update_row	更新表格中的现有行
nextcloud_tables_delete_row	删除表格中的一行

📁 WebDAV 文件系统工具（6 个工具）

工具	描述
nextcloud_webdav_search_files	🔍 全新！ 统一搜索文件名、内容和元数据，无需指定确切路径
nextcloud_webdav_list_directory	列出任意 Nextcloud 路径中的文件和目录
nextcloud_webdav_read_file	读取 Nextcloud 中的文件内容
nextcloud_webdav_write_file	在 Nextcloud 中创建或更新文件并写入内容
nextcloud_webdav_create_directory	在 Nextcloud 中创建新目录
nextcloud_webdav_delete_resource	从 Nextcloud 中删除文件或目录

🔍 革命性的 WebDAV 统一搜索功能

这款 MCP 服务的核心亮点是强大的 WebDAV 文件统一搜索系统，其灵感来自现代搜索界面，例如我创建的另一个 MCP：mcp-datagovmy。它彻底改变了你与 Nextcloud 文件的交互方式，无需再指定确切的文件路径。

✨ 主要功能

• 🎯 多范围搜索：同时搜索文件名、文件内容和元数据
• 🧠 智能文件类型检测：自动处理文本文件、代码、配置文件、文档和媒体文件
• 🔧 高级筛选：按文件类型、大小范围、修改日期和目录筛选
• 📈 智能排序：按相关性对结果排序，并为近期文件和精确匹配加权
• 👀 内容预览：可选预览匹配的文本文件内容
• ⚡ 性能优化：采用智能缓存、超时保护和并行处理
• 🛡️ 错误恢复：通过回退策略避免超时并提供实用建议

🚀 使用示例

// Basic search - find all files containing "FAQ Dean List"
await nextcloud_webdav_search_files({
  query: "FAQ Dean List"
});

// Advanced search - find PDF reports from 2024
await nextcloud_webdav_search_files({
  query: "report 2024",
  fileTypes: ["pdf"],
  searchIn: ["filename", "content"],
  limit: 20,
  includeContent: true,
  quickSearch: true
});

// Directory-specific search with date range
await nextcloud_webdav_search_files({
  query: "meeting notes",
  basePath: "/Documents",
  searchIn: ["filename", "content"],
  dateRange: {
    from: "2024-01-01",
    to: "2024-12-31"
  }
});

// Search by file characteristics
await nextcloud_webdav_search_files({
  query: "configuration files",
  sizeRange: { min: 1024, max: 102400 }, // 1KB - 100KB
  fileTypes: ["json", "yaml", "xml", "conf"]
});

// Quick search for large directories (optimized)
await nextcloud_webdav_search_files({
  query: "budget",
  basePath: "/", // Root directory
  quickSearch: true, // Enables optimizations
  limit: 25,
  maxDepth: 2 // Limit search depth
});

📋 完整参数参考

参数	类型	默认值	描述	示例
query	string	必填	搜索词，支持多个词	"FAQ Dean List"
searchIn	array	["filename", "content"]	搜索范围：filename、content、metadata	["filename", "content", "metadata"]
fileTypes	array	所有类型	要包含的文件扩展名	["pdf", "txt", "md", "docx"]
basePath	string	"/"	要搜索的目录	"/Documents/Reports"
limit	number	50	返回结果的最大数量	20
includeContent	boolean	false	包含文本文件的内容预览	true
caseSensitive	boolean	false	区分大小写匹配	true
quickSearch	boolean	true	在根目录搜索时使用优化模式	false
maxDepth	number	3	最大目录深度（1-10）	5
sizeRange	object	不限	文件大小筛选条件，单位为字节	{min: 1024, max: 1048576}
dateRange	object	所有日期	上次修改日期筛选条件	{from: "2024-01-01", to: "2024-12-31"}

🎯 性能提示

• 搜索根目录时：使用 quickSearch: true 和 maxDepth: 2-3，可更快获得结果
• 搜索特定目录时：使用 basePath: "/Documents"，而不是搜索根目录 "/"
• 结果集较大时：添加 fileTypes 筛选条件以缩小范围
• 出现超时问题时：启用 quickSearch 并使用较小的 limit 值

🧪 测试工具（1 个工具）

工具	描述
hello	验证服务连接并列出所有可用工具

🔄 搜索革新：前后对比

统一搜索之前

// You had to know exact paths
await nextcloud_webdav_read_file({
  path: "/Documents/Finance/Reports/Q4_Budget_Analysis_2024.pdf"
});

// Multiple calls needed to explore
await nextcloud_webdav_list_directory({ path: "/" });
await nextcloud_webdav_list_directory({ path: "/Documents" });
await nextcloud_webdav_list_directory({ path: "/Documents/Finance" });
// ... and so on

统一搜索之后 ✨

// Natural language search across entire Nextcloud!
await nextcloud_webdav_search_files({
  query: "Q4 budget analysis 2024",
  fileTypes: ["pdf"]
});

// Finds files instantly regardless of location!

🛠️ 高级搜索策略

内容感知搜索

系统会智能提取并搜索以下文件的内容：

• 📝 文本文件：.txt、.md、.csv - 对全文建立索引
• 💻 代码文件：.js、.ts、.py、.html、.css - 语法感知搜索
• ⚙️ 配置文件：.json、.xml、.yaml - 结构感知索引
• 📄 文档：.pdf、.docx - 元数据和属性
• 🎬 媒体文件：图像、视频 - EXIF 数据和元数据

智能排序系统

使用高级算法对结果进行排序：

1. 文件名完全匹配 → 100 分
2. 文件名中的单词边界匹配 → 80 分
3. 文件名部分匹配 → 60 分以上（位置加分）
4. 内容中的词频匹配 → 50 分以上（词语密度）
5. 近期文件加分 → +10 分（最近 30 天）
6. 文件类型偏好 → +5 分（文本/代码文件）
7. 文件大小适宜加分 → +5 分（小于 100KB 的文件）

错误处理与恢复

• 🕐 20 秒超时保护 - 防止操作卡住
• 🔄 自动备用搜索 - 索引失败时回退到目录列表
• 💡 智能建议 - 提供实用的优化提示
• 📊 性能指标 - 显示搜索耗时和结果数量

安装

使用 npm 快速开始（推荐）

直接从 npm 安装并作为 MCP 服务运行：

# Install globally
npm install -g mcp-nextcloud

# Or install locally in your project
npm install mcp-nextcloud

作为 MCP 服务使用

安装后，可直接运行 MCP 服务：

# If installed globally
mcp-nextcloud

# If installed locally
npx mcp-nextcloud

# Or using npm script
npm exec mcp-nextcloud

环境设置：创建 .env 文件并填入 Nextcloud 凭据：

NEXTCLOUD_HOST=https://your.nextcloud.instance.com
NEXTCLOUD_USERNAME=your_nextcloud_username
NEXTCLOUD_PASSWORD=your_nextcloud_app_password

与大模型应用集成

将以下内容添加到 MCP 客户端配置中（例如 Claude Desktop、Continue 等）：

CLI 模式（本地、单用户）：

{
  "mcpServers": {
    "nextcloud": {
      "command": "mcp-nextcloud",
      "env": {
        "NEXTCLOUD_HOST": "https://your.nextcloud.instance.com",
        "NEXTCLOUD_USERNAME": "your_username",
        "NEXTCLOUD_PASSWORD": "your_app_password"
      }
    }
  }
}

托管 HTTP 模式（通过 MCP Key Service）：

{
  "mcpServers": {
    "nextcloud": {
      "transport": "streamable-http",
      "url": "https://mcp.techmavie.digital/nextcloud/mcp/usr_XXXXXXXX"
    }
  }
}

托管客户端推荐配置： 对于 Claude.ai 及类似的托管连接器，请使用基于路径的 URL 格式（/mcp/usr_...）。将查询参数形式保留为兼容选项，供检查器和能够可靠保留查询参数的客户端使用。

自托管 HTTP 模式（使用自己的服务）：

{
  "mcpServers": {
    "nextcloud": {
      "transport": "streamable-http",
      "url": "https://mcp.techmavie.digital/nextcloud/mcp",
      "headers": {
        "X-API-Key": "your-server-api-key",
        "X-Nextcloud-Host": "https://your.nextcloud.instance.com",
        "X-Nextcloud-Username": "your_username",
        "X-Nextcloud-Password": "your_app_password"
      }
    }
  }
}

前置条件

• Node.js 18+
• 可访问 Nextcloud 实例
• npm 或 yarn 包管理器

本地开发设置

1. 克隆仓库：

   git clone https://github.com/hithereiamaliff/mcp-nextcloud.git
   cd mcp-nextcloud
   

2. 安装依赖：

   npm install
   

3. 配置 Nextcloud 凭据（参见配置部分）

4. 构建项目：

   npm run build
   

配置

环境变量

根据 .env.sample 在根目录中创建一个 .env 文件：

# --- CLI/stdio mode only ---
# These are used when running the server in CLI mode (npm run dev, npm run cli).
# They are NOT used by the HTTP server.
NEXTCLOUD_HOST=https://your.nextcloud.instance.com
NEXTCLOUD_USERNAME=your_nextcloud_username
NEXTCLOUD_PASSWORD=your_nextcloud_app_password

# --- HTTP server: Self-Hosted mode ---
# Required for self-hosted /mcp auth, and also used for /analytics access.
MCP_API_KEY=your-secret-api-key-here

# --- HTTP server: Key Service mode ---
# Set both to enable user api_key=usr_... resolution via the MCP Key Service.
# Users obtain and manage those keys at https://mcpkeys.techmavie.digital
# The MCP server itself talks to the resolver endpoint below.
KEY_SERVICE_URL=https://mcpkeys.techmavie.digital/internal/resolve
KEY_SERVICE_TOKEN=your-key-service-bearer-token

# Optional: Comma-separated list of allowed CORS origins.
ALLOWED_ORIGINS=https://smithery.ai,https://claude.ai

# Optional diagnostics for remote MCP debugging.
# These are intended for temporary troubleshooting in hosted HTTP mode.
MCP_TRACE_HTTP=false
ENABLE_MCP_DIAGNOSTICS=false

# Optional dedicated endpoint for Smithery URL publishing.
ENABLE_SMITHERY_ENDPOINT=false

重要安全提示：

• 使用专用的 Nextcloud 应用密码，而非常规登录密码。请在 Nextcloud 的安全设置中生成应用密码。
• 在 HTTP 模式下，永远不会使用 NEXTCLOUD_* 环境变量。可自托管客户端通过 X-Nextcloud-* 标头提供凭据，而密钥服务客户端只发送一个 usr_... 密钥。
• 生成强 API 密钥：openssl rand -hex 32

Smithery 配置

通过 Smithery 部署时，可以通过以下方式配置凭据：

• URL 发布型服务的 Smithery 配置界面

对于 Smithery，建议采用以下模式：

• 用户直接输入 nextcloudHost、nextcloudUsername 和 nextcloudPassword
• Smithery 将这些值作为标头转发到专用的 /smithery/mcp 端点
• 托管的 usr_... 密钥服务流程保持独立，并继续使用 /mcp/usr_...

部署与使用

选项 1：托管服务（推荐）

使用此 MCP 服务最简单的方式是通过托管端点。无需安装！

端点： https://mcp.techmavie.digital/nextcloud/mcp

身份验证

托管服务使用 MCP Key Service 进行身份验证。你可以从 MCP Key Service 门户获取个人 API 密钥（usr_XXXXXXXX）：

https://mcpkeys.techmavie.digital

随后，服务会在后台通过解析器端点自动解析你的 Nextcloud 凭据。

这种方式为何比旧的查询参数凭据方式更安全：

• 原始 Nextcloud 凭据不会嵌入连接器 URL
• 撤销 usr_... 密钥比在各处轮换用户的 Nextcloud 密码更容易
• 更容易集中管理服务端审计和策略
• 支持和调试工作流更安全，因为用户共享的是受限范围的密钥，而非真实的 Nextcloud 密码

Claude.ai / 托管连接器 URL（推荐）：

https://mcp.techmavie.digital/nextcloud/mcp/usr_XXXXXXXX

适用于能正确保留查询参数的客户端的备用 URL：

https://mcp.techmavie.digital/nextcloud/mcp?api_key=usr_XXXXXXXX

客户端配置

{
  "mcpServers": {
    "nextcloud": {
      "transport": "streamable-http",
      "url": "https://mcp.techmavie.digital/nextcloud/mcp/usr_XXXXXXXX"
    }
  }
}

使用 MCP Inspector 测试

npx @modelcontextprotocol/inspector
# Select "Streamable HTTP"
# Enter URL: https://mcp.techmavie.digital/nextcloud/mcp/usr_XXXXXXXX

选项 2：自托管（VPS）

如果你更愿意运行自己的实例，内置的 Docker + Nginx 设置如下：

# Set required environment variables
export MCP_API_KEY=your-secret-api-key  # Required for self-hosted /mcp auth and /analytics
export KEY_SERVICE_URL=https://mcpkeys.techmavie.digital/internal/resolve  # Optional: enables key service mode
export KEY_SERVICE_TOKEN=your-key-service-bearer-token                      # Optional: enables key service mode

# Using Docker
docker compose up -d --build

# Or run directly
npm run build
npm run start:http

推荐的 VPS 配置

1. 将仓库克隆到服务器：

   git clone https://github.com/hithereiamaliff/mcp-nextcloud.git
   cd mcp-nextcloud
   

2. 创建 .env 文件并填写服务器设置：

   MCP_API_KEY=your-secret-api-key
   KEY_SERVICE_URL=https://mcpkeys.techmavie.digital/internal/resolve
   KEY_SERVICE_TOKEN=your-key-service-bearer-token
   ALLOWED_ORIGINS=https://smithery.ai,https://claude.ai
   ENABLE_SMITHERY_ENDPOINT=false
   

   说明：
   • 只有在需要托管式 usr_... 密钥解析时，才使用 KEY_SERVICE_URL + KEY_SERVICE_TOKEN。
   • 用户在 https://mcpkeys.techmavie.digital 获取和管理这些密钥。
   • MCP 服务本身应继续使用解析器端点路径，而不是门户首页。
   • 只有在需要发布专用的 Smithery 直接凭据端点时，才设置 ENABLE_SMITHERY_ENDPOINT=true。
3. 启动容器：

   docker compose up -d --build
   

4. 将 deploy/nginx-mcp.conf 中的反向代理配置添加到 nginx 服务器配置块。
5. 验证并重新加载 nginx：

   sudo nginx -t
   sudo systemctl reload nginx
   

6. 验证服务：

   curl http://127.0.0.1:8080/health
   

重要： HTTP 服务不会使用 NEXTCLOUD_* 环境变量。在可自托管模式下，每个客户端都必须通过请求标头提供 Nextcloud 凭据。在密钥服务模式下，客户端只发送 api_key=usr_...。

远程 MCP 说明： 对于 Claude.ai 等托管连接器，建议使用基于路径的 URL 形式（/mcp/usr_...）。将查询参数形式保留为兼容选项，供检查器及能够可靠保留查询参数的客户端使用。

调试说明： 如果托管客户端显示通用身份验证提示，并不代表一定需要 OAuth。请先检查免身份验证诊断路由、密钥服务解析器响应，以及实际的 initialize SSE 正文。

选项 3：npm 包（CLI）

安装并作为本地 MCP 服务运行：

npm install -g mcp-nextcloud
mcp-nextcloud

注意： 在 CLI 模式下，凭据从环境变量（NEXTCLOUD_HOST、NEXTCLOUD_USERNAME、NEXTCLOUD_PASSWORD）中读取。这是安全的，因为 CLI 模式在本地为单个用户运行。

选项 4：Smithery 部署

对于 Smithery 当前基于发布 URL 的模式，请使用专用端点，通过标头接受直接 Nextcloud 凭据：

# Enable the Smithery endpoint on your hosted server
ENABLE_SMITHERY_ENDPOINT=true

在 Smithery 中使用此公开 MCP URL：

https://mcp.techmavie.digital/nextcloud/smithery/mcp

此服务推荐的 Smithery 配置架构：

{
  "type": "object",
  "properties": {
    "nextcloudHost": {
      "type": "string",
      "title": "Nextcloud Host",
      "description": "Nextcloud server URL (for example https://cloud.example.com)",
      "x-from": { "header": "X-Nextcloud-Host" }
    },
    "nextcloudUsername": {
      "type": "string",
      "title": "Nextcloud Username",
      "x-from": { "header": "X-Nextcloud-Username" }
    },
    "nextcloudPassword": {
      "type": "string",
      "title": "Nextcloud App Password",
      "format": "password",
      "x-from": { "header": "X-Nextcloud-Password" }
    }
  },
  "required": ["nextcloudHost", "nextcloudUsername", "nextcloudPassword"]
}

推荐采用这种拆分方式的原因：

• Smithery 用户无需先创建 MCP Key Service 密钥即可直接连接
• Claude.ai 和其他托管客户端的托管式 usr_... 连接器流程保持不变
• Smithery 路径独立使用 /smithery/mcp，不会影响 /mcp 或 /mcp/usr_...

重要： Smithery 端点专为通过标头传递直接凭据而设计。它不使用 MCP Key Service，也不需要共享的 MCP_API_KEY。

为帮助 Smithery 发现工具，同时避免强制执行实时身份验证扫描，此服务还在 https://mcp.techmavie.digital/.well-known/mcp/server-card.json 提供静态服务卡片。如果反向代理将应用挂载在 /nextcloud 下，请确保将这个精确的根级 well-known 路径代理到应用。

发布到 npm

维护者须知

要将此包发布到 npm：

1. 准备发布：

   npm run build
   npm version patch|minor|major
   

2. 发布到 npm：

   npm publish
   

3. 验证发布：

   npm view mcp-nextcloud
   

发布检查清单

• 所有测试均通过（已确认 Smithery 部署正常运行）
• TypeScript 构建无错误（npm run build）
• 已适当更新版本（npm version）
• README 已更新，包含变更内容
• .npmignore 已正确排除开发文件
• CLI 可执行文件可正常运行（dist/cli.js）

双重部署策略

此项目同时支持两种部署方式：

• Smithery：用于云端部署和开发测试
• npm：用于终端用户安装和 MCP 客户端集成

Smithery 配置（smithery.yaml）和 npm 包配置可以共存，互不干扰。

Smithery 集成

本项目全面支持 Smithery，包括：

• smithery.yaml：指定 TypeScript 运行时
• 开发服务器：支持热重载的本地测试
• 一键部署：通过一条命令部署到云端
• 配置管理：安全地处理凭据
• Playground 集成：提供可立即使用的测试界面

安全性

HTTP 服务器安全模型

HTTP 服务器（http-server.ts）支持两种身份验证模式：

密钥服务模式（托管式／多用户）：

• 用户 API 密钥（usr_...）通过 MCP 密钥服务解析，该服务会返回经过加密的 Nextcloud 凭据。
• 客户端不会发送原始凭据，只发送用户专属的 API 密钥。
• 凭据会缓存 60 秒以减轻密钥服务的负载，之后会重新验证。

自托管模式（单一运营者）：

• 服务器端的 MCP_API_KEY 用于验证访问权限。
• 每个客户端都通过 X-Nextcloud-* 标头提供 Nextcloud 凭据。

通用安全措施：

• 按请求隔离凭据：每个请求都会通过 AsyncLocalStorage 获得一组独立的 Nextcloud 客户端。请求之间不会共享凭据状态。
• 不回退到环境变量：HTTP 服务器绝不会回退到使用 NEXTCLOUD_* 环境变量作为凭据。这些变量仅用于 CLI 模式。
• 限制 CORS：仅允许 ALLOWED_ORIGINS 中列出的来源（默认为 smithery.ai 和 claude.ai）。
• 保护分析功能：两种模式下，/analytics 端点都要求通过 MCP_API_KEY 进行身份验证。仪表板页面会将密钥存储在会话存储中，绝不会放在 URL 中。存储前会对客户端 IP 进行哈希处理。
• 生产环境中禁用调试工具：当 NODE_ENV=production 时，会自动禁用日历调试工具。

自托管检查清单

如果要部署自己的实例：

1. 选择一种身份验证模式：为密钥服务设置 KEY_SERVICE_URL + KEY_SERVICE_TOKEN，或为自托管模式设置 MCP_API_KEY
2. 设置 MCP_API_KEY 以访问分析功能（两种模式下均为必需）
3. 不要在 HTTP 服务器上设置 NEXTCLOUD_* 环境变量
4. 对所有连接使用 HTTPS（TLS）
5. 配置 ALLOWED_ORIGINS，以限制可连接的域名
6. 使用 Nextcloud 应用密码（而非主登录密码）

故障排除

常见问题

1. WebDAV／日历／联系人出现 404 错误：

   • 确认 Nextcloud 凭据正确
   • 确认已安装并启用 Nextcloud 应用（日历、联系人）
   • 检查应用密码是否具有所需权限

2. 身份验证失败：

   • 使用应用密码，而非常规密码
   • 确认 NEXTCLOUD_HOST URL 正确（包括 https://）
   • 确认可以访问 Nextcloud 实例

3. 缺少工具：

   • 运行 hello 工具，确认 30 个工具均可用
   • 检查服务器日志中是否有初始化错误

4. 搜索超时问题：

   • 搜索根目录时使用 quickSearch: true
   • 指定类似 "/Documents" 的 basePath，而不是搜索根目录 "/"
   • 添加 fileTypes 筛选条件以缩小搜索范围
   • 减小 maxDepth 参数，以加快结果返回速度

托管 HTTP / Claude.ai 调试

如果托管连接器仍然无法使用，请按以下顺序排查：

1. 先验证无需身份验证的诊断路由：
   • 启用 ENABLE_MCP_DIAGNOSTICS=true
   • 测试 /mcp-debug/open
   • 如果此路由正常工作，问题很可能出在身份验证或上游依赖项，而不是基本的 MCP 传输
2. 直接从已部署的 MCP 主机验证密钥服务解析器：

   curl -i -X POST "$KEY_SERVICE_URL" \
     -H "Authorization: Bearer $KEY_SERVICE_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"key":"usr_..."}'
   

   预期结果：
   • 200 OK
   • Content-Type: application/json
   • 有效的 JSON 响应
3. 验证 MCP 初始化响应正文，而不仅仅是状态码：

   curl -N --max-time 10 -X POST "https://mcp.techmavie.digital/nextcloud/mcp/usr_XXXXXXXX" \
     -H "Content-Type: application/json" \
     -H "Accept: application/json, text/event-stream" \
     -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"probe","version":"1.0.0"}}}'
   

   预期结果：
   • 200 OK
   • Content-Type: text/event-stream
   • 非空的 SSE 初始化响应正文
4. 如果托管客户端每隔几秒就重复发送相同的初始化请求，即使 HTTP 状态为 200，也应怀疑 SSE 初始化响应为空或格式错误。
5. 启用临时跟踪 MCP_TRACE_HTTP=true 并检查：
   • 最终状态码
   • 请求 accept
   • 请求 content-type
   • content-type 响应标头
   • 身份验证结果（resolved、invalid_key、service_unavailable、malformed_response）

开发

项目结构

├── src/
│   ├── index.ts          # Main Smithery entry point
│   ├── http-server.ts    # Streamable HTTP server for VPS deployment
│   ├── app.ts            # Legacy entry point
│   ├── client/           # Nextcloud API clients
│   ├── models/           # TypeScript interfaces
│   ├── tools/            # Tool implementations
│   └── utils/            # Utility functions
├── deploy/
│   └── nginx-mcp.conf    # Nginx reverse proxy config
├── .github/
│   └── workflows/
│       └── deploy-vps.yml # GitHub Actions auto-deploy
├── docker-compose.yml    # Docker deployment config
├── Dockerfile            # Container build config
├── smithery.yaml         # Smithery configuration
├── package.json          # Project dependencies and scripts
└── README.md             # This file

参与贡献

1. Fork 此仓库
2. 创建功能分支
3. 进行更改
4. 使用 npm run dev 进行测试
5. 提交拉取请求

许可证

本项目采用 GNU Affero 通用公共许可证 v3.0（AGPL-3.0）授权；详情请参阅 LICENSE 文件。

致谢

• 原始 Python 实现由 cbcoutinho 编写
• 使用 Model Context Protocol 构建
• 可通过 Smithery 部署