hithereiamaliff-mcp-nextcloud

Nextcloud MCP サーバー

MCP エンドポイント： https://mcp.techmavie.digital/nextcloud/mcp

注： このプロジェクトは、オリジナルの Python ベースの cbcoutinho/nextcloud-mcp-server を TypeScript で完全に書き直したもので、セルフホスト可能な VPS へのデプロイとSmithery へのデプロイをサポートしています。

オリジナルのリポジトリとの主な違い：

• 言語： このプロジェクトは TypeScript で記述されていますが、オリジナルは Python で記述されています。
• Smithery のサポート： Smithery へのデプロイと、Smithery プレイグラウンド経由のローカルテストを完全にサポートしました。
• プロジェクト構成： MCP SDK 統合を備えた Node.js／TypeScript 環境に合わせて、プロジェクト構成を変更しています。
• 依存関係： このプロジェクトはパッケージ管理に npm を使用しますが、オリジナルは Python の依存関係管理ツールを使用しています。
• デプロイ： ローカル開発と Smithery 経由のクラウドデプロイの両方をサポートするようになりました。

Nextcloud MCP（Model Context Protocol）サーバーを使用すると、OpenAI の GPT、Google の Gemini、Anthropic の Claude などの大規模言語モデル（LLM）が Nextcloud インスタンスとやり取りできます。これにより、Notes、Calendar、Contacts、Tables、WebDAV のファイル操作など、さまざまな Nextcloud アクションを自動化できます。

ホスト型 HTTP 統合では、MCP Key Service を通じて、より安全なマルチユーザーフローをサポートするようになりました。コネクタ URL に Nextcloud の認証情報をそのまま埋め込む代わりに、ホスト型クライアントはユーザーごとにスコープ設定された usr_... キーを使用し、サーバー側で認証情報を解決できます。

機能

このサーバーは複数の Nextcloud アプリと連携し、5 つの主なカテゴリにわたる30 個のツールを通じて、LLM が 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

環境の設定：Nextcloud の認証情報を記載した .env ファイルを作成します。

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

LLM アプリケーションとの統合

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 キーサービスを使用します。MCP キーサービスポータルで個人用 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 のキーを作成せずに直接接続できます。
• ホスト型の usr_... コネクターフローは、Claude.ai やその他のホスト型クライアント向けに従来どおり利用できます。
• 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 ランタイムを指定します
• 開発サーバー：ホットリロードによるローカルテスト
• ワンクリックデプロイ：1 つのコマンドでクラウドにデプロイできます
• 構成管理：認証情報を安全に管理します
• プレイグラウンドとの連携：すぐにテストできるインターフェース

セキュリティ

HTTP サーバーのセキュリティモデル

HTTP サーバー（http-server.ts）では、2 つの認証モードをサポートしています。

キーサービスモード（ホスト型／マルチユーザー）：

• ユーザー API キー（usr_...）は MCP Key Service を介して解決され、暗号化された 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. リポジトリをフォークします
2. 機能ブランチを作成します
3. 変更を加えます
4. npm run dev でテストします
5. プルリクエストを送信します

ライセンス

このプロジェクトは GNU Affero General Public License v3.0（AGPL-3.0）の下でライセンスされています。詳細は LICENSE ファイルを参照してください。

謝辞

• cbcoutinho によるオリジナルの Python 実装
• Model Context Protocol を使用して構築
• Smithery 経由でデプロイ可能