MCP Nextcloud Calendar

🚀 MCP Nextcloud Calendar

MCP Nextcloud Calendar 是一个用于集成 Nextcloud 日历的模型上下文协议（MCP）服务器，它能从 Nextcloud 中获取日历信息，并提供对 ADHD 友好的组织功能，同时支持 MCP 协议。

🚀 快速开始

你可以使用 npx 快速使用该包：

npx mcp-nextcloud-calendar

✨ 主要特性

• 从 Nextcloud 获取日历信息。
• 具备对 ADHD 友好的组织功能。
• 支持 MCP 协议（可流式传输的 HTTP 和传统的 HTTP+SSE）。

📦 安装指南

全局安装

npm install -g mcp-nextcloud-calendar

本地安装

npm install mcp-nextcloud-calendar

💻 使用示例

MCP 客户端配置

若要与 MCP 客户端（如 Claude）配合使用，请将以下配置添加到你的 MCP 客户端设置中：

{
  "mcpServers": {
    "nextcloud-calendar": {
      "command": "npx",
      "args": ["-y", "mcp-nextcloud-calendar"],
      "env": {
        "NEXTCLOUD_BASE_URL": "https://your-nextcloud-server.com",
        "NEXTCLOUD_USERNAME": "your-username",
        "NEXTCLOUD_APP_TOKEN": "your-app-token"
      }
    }
  }
}

指定版本

你可以固定使用该包的特定版本：

{
  "mcpServers": {
    "nextcloud-calendar": {
      "command": "npx",
      "args": ["-y", "mcp-nextcloud-calendar@0.1.0"],
      "env": {
        "NEXTCLOUD_BASE_URL": "https://your-nextcloud-server.com",
        "NEXTCLOUD_USERNAME": "your-username",
        "NEXTCLOUD_APP_TOKEN": "your-app-token"
      }
    }
  }
}

📚 详细文档

环境变量

服务器使用以下环境变量，并在可能的情况下提供默认值：

开发设置

本地开发步骤

1. 克隆仓库。
2. 安装依赖：

npm install

3. 在项目根目录创建 .env 文件：

cp .env.example .env

4. 使用你的 Nextcloud 凭证编辑 .env 文件。

获取 Nextcloud 应用令牌

1. 登录你的 Nextcloud 实例。
2. 转到设置 → 安全 → 应用密码。
3. 创建一个名为“MCP Calendar”的新应用密码。
4. 将生成的令牌复制到你的 .env 文件中。

开发命令

# 构建项目
npm run build

# 以开发模式运行
npm run dev

# 运行测试
npm run test

# 运行代码检查
npm run lint

# 格式化代码
npm run format

🔧 技术细节

API 端点

• /mcp - 主要的 MCP 端点（可流式传输的 HTTP 传输）。
• /sse 和 /messages - 传统的 MCP 端点（HTTP+SSE 传输）。
• GET /health - 健康检查端点。
• GET /api/calendars - 列出所有日历。

MCP 工具

日历管理

⚠️ 重要提示

updateCalendar 和 deleteCalendar 工具可能需要你的 Nextcloud 实例中的特殊权限。日历操作受 Nextcloud 的权限系统约束。

事件管理

📄 许可证

本项目采用 ISC 许可证。

⚠️ 重要提示

此包目前处于早期开发阶段（0.1.x）。API 和工具可能会在未来版本中无通知更改。

💡 使用建议

• 更新和删除日历操作可能需要你的 Nextcloud 实例中的特定权限。
• 针对特定 Nextcloud 错误代码的错误处理仍在改进中。
• 包含大量事件的大型日历可能会出现性能问题。

如果你遇到任何问题，请在 GitHub 仓库中报告。