使用说明

🌐 NextCloud MCP服务器

用于无缝NextCloud集成的专业模型上下文协议（MCP）服务器

为您的AI代理提供全面的NextCloud文件管理和共享功能

🚀 特性

📁 文件管理	🔗 共享	🔒 安全	🛠️ 开发者体验
列表、上传、下载	公共链接	应用密码	完全支持TypeScript
创建目录	用户/组共享	环境变量	综合测试
删除文件/文件夹	密码保护	安全身份验证	专业文档
移动和重命名	到期日期	HTTPS强制	易于集成

✨ 关键能力

🎯 14综合工具 -完成文件操作和共享管理
🔐 增强的安全性 -内置应用程序密码支持和最佳实践
🏗️ 专业建筑 -TypeScript优先，具有完全类型安全性
📚 丰富的文档 -详细指南和示例
🔄 WebDAV集成 -原生NextCloud协议支持
⚡ 高性能 -针对速度和可靠性进行了优化
🌍 通用兼容性 -适用于任何NextCloud实例

📦 安装

来自NPM（推荐）

# Install globally for CLI usage
npm install -g nextcloud-mcp-server

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

来源

git clone https://github.com/abdullahMASHUK/nextcloud-mcp-server.git
cd nextcloud-mcp-server
npm install
npm run build

🚀 快速开始

1.🔐 设置应用程序密码（推荐）

Click to expand security setup instructions

为了增强安全性，请创建专用的应用程序密码：

导航到NextCloud设置

NextCloud → Settings → Security → App passwords

创建新应用密码
- 输入名称： MCP Server
- 点击“创建新应用密码”
- 复制生成的密码： xxxxx-xxxxx-xxxxx-xxxxx-xxxxx
为什么要使用应用程序密码？
- ✅ 范围和权限有限
- ✅ 可以独立撤销
- ✅ 无法访问您的主帐户
- ✅ 可审计的访问日志

2.⚙️ 配置

# Copy the environment template
cp .env.example .env

编辑您的 .env 文件：

NEXTCLOUD_URL=https://your-nextcloud-server.com
NEXTCLOUD_USERNAME=your-username
NEXTCLOUD_PASSWORD=your-app-password-here  # Use app password!

3.🎮 与MCP客户端一起使用

Claude Desktop Configuration

添加到您的 claude_desktop_config.json:

{
  "mcpServers": {
    "nextcloud": {
      "command": "nextcloud-mcp-server",
      "env": {
        "NEXTCLOUD_URL": "https://your-nextcloud-server.com",
        "NEXTCLOUD_USERNAME": "your-username",
        "NEXTCLOUD_PASSWORD": "your-app-password"
      }
    }
  }
}

Direct Usage

# Run the MCP server
nextcloud-mcp-server

# Or with Node.js
node build/index.js

🛠️ 可用工具

📁 文件操作

🔍 test-connection	Test connectivity to your NextCloud server
📋 list-files	List files and directories with metadata
📁 create-directory	Create new directories in NextCloud
🗑️ delete-file	Delete files or directories
⬆️ upload-file	Upload files with base64 encoding
⬇️ download-file	Download files from NextCloud
🔄 move-file	Move or rename files and directories
📄 copy-file	Copy files and directories to new locations
🔍 search-files	Search for files and directories by name or content
📚 get-file-versions	Get version history of a file
🔄 restore-file-version	Restore a specific version of a file

🔗 共享操作

🌐 create-share	Create public links, user, or group shares
📤 list-shares	List and filter existing shares
🗑️ delete-share	Remove shares by ID

📖 文档

🎯 工具示例

📋 List Files

{
  "name": "list-files",
  "arguments": {
    "path": "/Documents"
  }
}

答复： 返回包含元数据（名称、大小、类型、修改日期）的文件数组

⬆️ Upload File

{
  "name": "upload-file",
  "arguments": {
    "remotePath": "/documents/report.pdf",
    "content": "JVBERi0xLjQK..."  // base64 encoded content
  }
}

🔄 Move File

{
  "name": "move-file",
  "arguments": {
    "sourcePath": "/old-location/document.pdf",
    "destinationPath": "/new-location/document.pdf",
    "overwrite": false
  }
}

答复： 带有源和目标路径的确认消息

📄 Copy File

{
  "name": "copy-file",
  "arguments": {
    "sourcePath": "/Documents/template.docx",
    "destinationPath": "/Projects/new-document.docx",
    "overwrite": true
  }
}

答复： 带有复制操作详细信息的确认消息

🔍 Search Files

{
  "name": "search-files",
  "arguments": {
    "query": "quarterly report",
    "path": "/Documents",
    "limit": 20,
    "type": "file"
  }
}

答复： 具有完整元数据的匹配文件数组

类型选项： file, directory, all

📚 Get File Versions

{
  "name": "get-file-versions",
  "arguments": {
    "path": "/Documents/important-document.pdf"
  }
}

答复： 包含时间戳、大小和用户信息的文件版本数组

🔄 Restore File Version

{
  "name": "restore-file-version",
  "arguments": {
    "path": "/Documents/important-document.pdf",
    "versionId": "1672531200"
  }
}

答复： 版本恢复确认

🌐 Create Share

{
  "name": "create-share",
  "arguments": {
    "path": "/Documents/presentation.pptx",
    "shareType": 3,
    "password": "secure123",
    "expireDate": "2024-12-31",
    "note": "Shared for team review"
  }
}

共享类型：

0 -用户分享
1 -集团份额
3 -公共链接
4 -电子邮件共享

🏗️ 发展

Setup Development Environment

# Clone and install
git clone https://github.com/abdullahMASHUK/nextcloud-mcp-server.git
cd nextcloud-mcp-server
npm install

# Development commands
npm run dev          # Run with auto-reload
npm run build        # Build TypeScript
npm run test         # Run test suite
npm run lint         # Check code quality
npm run format       # Format code

项目结构：

src/
├── index.ts              # Main MCP server
├── services/
│   └── nextcloud.ts      # NextCloud API client
├── types.ts              # TypeScript definitions
└── utils/                # Utility functions

__tests__/                # Test suites
build/                    # Compiled output

🔒 安全

🛡️ 最佳实践

✅ 做	❌ 不要
使用应用程序密码	使用主帐户密码
存储在环境变量中	硬编码凭据
使用HTTPS URL	使用HTTP连接
定期轮换密码	保留旧密码
监视访问日志	忽略安全事件

🔐 安全功能

🔑 应用程序密码集成 -专用身份验证令牌
🌐 HTTPS强制 -需要安全连接
📝 环境变量 -安全凭证存储
🔍 错误处理 -日志中没有凭据暴露
🛡️ 权限范围界定 -有限的访问权限

⚠️ 安全检查列表

[]已创建并配置应用程序密码
[]NextCloud服务器上已启用HTTPS
[]环境变量设置正确
[ ] .env 文件已添加到 .gitignore
[]计划定期轮换密码

许可证

MIT许可证-有关详细信息，请参阅许可证文件。

🤝 贡献

我们欢迎捐款！

🚀 How to Contribute

🍴 分叉存储库

🌿 创建功能分支

git checkout -b feature/amazing-feature

💻 进行更改
✅ 为新功能添加测试
🧪 运行测试套件
```
npm run test
npm run lint
```

📝 提交您的更改

git commit -m "✨ Add amazing feature"

🚀 推到您的分支

git push origin feature/amazing-feature

🔄 打开拉取请求

💡 贡献方式

🐛 Bug Reports	✨ Feature Requests	📚 Documentation	🧪 Testing
Found an issue? Report it!	Have an idea? Share it!	Improve docs and examples	Add tests and improve coverage

💖 支持

表示支持！ ⭐

如果这个项目对你有帮助，请考虑给它一个⭐ 在GitHub上！

🗣️ 获得帮助

🔗 联系我们

📜 许可证

特此免费授予任何获得此软件副本的人许可。..

📖 阅读完整许可证

📈 更新日志

Version History

🎉 v1.0.3

🎨 使用专业格式和视觉增强功能美化README
📊 添加了交互式表格、徽章和可折叠部分
👤 更新了作者信息和git配置
🔗 使用表情符号增强导航和更好的组织
✨ 改善了npm和GitHub查看器的用户体验

🚀 v1.0.2

✨ 增强的文档和README
🔒 增加了全面的安全指南
📝 改进的TypeScript定义
🐛 Bug修复和稳定性改进

🚀 v1.0.1

📚 更新文件
🔧 配置改进
🛠️ 构建流程优化

🌟 v1.0.0

🎊 初始版本
📁 基本文件操作（列表、上传、下载、删除）
🔗 共享管理（创建、列出、删除）
🔧 TypeScript实现
✅ 全面的测试覆盖率
📖 全部文件

由以下材料制成❤️ 靠近阿卜杜拉·马苏克

在NextCloud和AI助手之间搭建桥梁 🌉