MCP Nextcloud Calendar

🚀 MCP Nextcloud Calendar

Nextcloudカレンダーを統合するためのModel Context Protocol (MCP)サーバーです。

🚀 クイックスタート

このパッケージを使用する最も簡単な方法は、npxを使うことです。

npx mcp-nextcloud-calendar

✨ 主な機能

• Nextcloudからカレンダーを取得します。
• ADHDに配慮した組織機能が備わっています。
• MCPプロトコル（Streamable HTTPおよびLegacy 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エンドポイント（Streamable HTTPトランスポート）
• /sse および /messages - レガシーMCPエンドポイント（HTTP+SSEトランスポート）
• GET /health - ヘルスチェックエンドポイント
• GET /api/calendars - すべてのカレンダーをリストする

MCPツール

以下のMCPツールが登録されており、クライアントから利用できます。

カレンダー管理

⚠️ 重要提示

updateCalendar および deleteCalendar ツールは、Nextcloudインスタンスで特定の権限が必要になる場合があります。カレンダー操作はNextcloudの権限システムに従います。

イベント管理

既知の問題と制限事項

⚠️ 重要提示

このパッケージは現在初期開発段階（0.1.x）です。将来のリリースでAPIやツールが予告なく変更される可能性があります。

• カレンダーの更新および削除操作は、Nextcloudインスタンスで特定の権限が必要になる場合があります。
• 特定のNextcloudエラーコードのエラーハンドリングはまだ改善されていません。
• 多数のイベントを持つ大規模なカレンダーでは、パフォーマンスの問題が発生する可能性があります。

問題があれば、GitHubリポジトリに報告してください。

📄 ライセンス

ISC