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 客戶端（如 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. 編輯 .env 文件，填入你的 Nextcloud 憑證。

獲取 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 倉庫中報告。