librechat-personal-files-mcp

LibreChat エージェント向けに、ユーザーごとの個人ファイルストレージ、永続的なドキュメント、RAGインデックス/検索、そして不透明な公開リンク公開を提供するMCPサーバー。

機能

• ユーザーごとのストレージ: /data/private/<userId>/ 配下にプライベートファイルを保存し、完全なCRUD・一覧・移動操作をサポートします。

• ドキュメントカタログ: save_documentation / update_documentation は docs/ に書き込み、memory-index.json（スキーマv2）を更新します。

• RAG統合: index_document はコンテンツを POST /embed で rag_api に送信し、カナリア検証（issue #305）を行います。search_knowledge はセマンティック検索、remove_from_knowledge は削除に使用します。

• 公開リンク公開: publish_file は暗号学的にランダムなトークン（128ビット以上）を生成します。ファイルはNginx の X-Accel-Redirect と Content-Disposition: attachment、nosniff、no-store を通じて配信されます。

• 厳格なセキュリティ: X-User-Id が欠落または不正な場合はフェイルクローズします。パストラバーサルを遮断し、絶対パスや .. セグメントを拒否します。シンボリックリンクによるエスケープ検出、予約セグメントの保護、クロスプロセスロック付きのアトミックなインデックス書き込みを備えています。

Related MCP server: knowledge_mgmt

アーキテクチャ

┌──────────────┐     ┌────────────────────────┐     ┌─────────────┐
│ LibreChat    │────▶│ librechat-personal-files-mcp │──▶│ rag_api     │
│ (Agent)      │ MCP │ (stateless HTTP /mcp)  │     │ (vector DB) │
└──────────────┘     └────────────────────────┘     └─────────────┘
                            │
                            │ GET /files/{token}
                            ▼
                     ┌──────────────┐
                     │ Nginx        │
                     │ (X-Accel)    │
                     └──────────────┘
                            │
                            ▼
                     ┌──────────────┐
                     │ /data/private│  (read-only bind)
                     └──────────────┘

クイックスタート（開発）

cd /opt/LibreChat/mcp-personal-files
python -m venv .venv
.venv/bin/pip install -e ".[dev]"
.venv/bin/python -m pytest
.venv/bin/python -m ruff check .
# Run server
STORAGE_ROOT=/tmp/pf-private JWT_SECRET=$(openssl rand -hex 32) .venv/bin/personal-files-mcp

本番デプロイ

1. ホストの準備（root で一度だけ実行）

cd /opt/LibreChat
groupadd -g 2500 lcfiles 2>/dev/null || true
mkdir -p ./data/private/_system
chown -R 2000:2500 ./data/private
chmod 2770 ./data/private
setfacl -R -m g:2500:rX,d:g:2500:rX ./data/private 2>/dev/null || \
  echo "ACL tools absent; using 644/755 fallback"
grep -q '^JWT_SECRET=' .env || echo "JWT_SECRET=$(openssl rand -hex 32)" >> .env

2. docker-compose.override.yml に追加

docker-compose.snippet.yml のブロックを既存のオーバーライドファイルにコピーしてください。

3. LibreChat 管理パネルの設定

MCP設定の下に追加:

mcpSettings:
  allowedAddresses:
    - 'librechat-personal-files:8080'

mcpServers:
  personal-files:
    type: streamable-http
    url: http://librechat-personal-files:8080/mcp
    timeout: 120000
    chatMenu: false
    headers:
      X-User-ID: '{{LIBRECHAT_USER_ID}}'
      X-User-Email: '{{LIBRECHAT_USER_EMAIL}}'

LibreChat を再起動します。

4. Nginx設定（既存のserverブロックに追加）

limit_req_zone $binary_remote_addr zone=pubfiles:10m rate=5r/s;

location ^~ /files/ {
    limit_req zone=pubfiles burst=10 nodelay;
    limit_req_status 429;
    proxy_pass http://librechat-personal-files:8080/files/;
    proxy_set_header X-Original-URI $request_uri;
    proxy_set_header X-Real-IP $remote_addr;
}

location ^~ /_protected/ {
    internal;
    alias /data/private/;
}

Nginx をリロードします。

環境変数

MCPツール

ストレージ

• list_files(path="", recursive=false, pattern=null) — ファイル/ディレクトリの一覧表示

• read_file(path) — UTF-8テキストを読み取る。バイナリまたは2MB超の場合はエラー

• write_file(path, content) — テキスト（UTF-8）を書き込む。親ディレクトリも作成

• update_file(path, content) — 既存ファイルを更新

• delete_file(path) — ファイルまたはディレクトリを削除

• move_file(src, dst) — ユーザールート内で移動

• get_file_info(path) — メタデータ + docindex + 公開ステータス

ドキュメント

• save_documentation(filename, content, title?, description?, tags?, topics?) — docs/ に保存し、インデックスを更新。公開やインデックス化は行いません

• update_documentation(filename, content, ...) — 既存ドキュメントを更新

• get_document_metadata(filename) — 完全なインデックスエントリを取得

RAG

• search_knowledge(query, limit=8) — セマンティック検索（JWTにより所有者スコープ）

• index_document(path) — エンベディング + カナリア検証を行い、インデックスステータスを更新

• remove_from_knowledge(path) — rag_api から削除し、インデックスをクリア

• get_index_status() — 件数 + rag_api のヘルスステータス

公開

• publish_file(path, expires_in_days?) — 公開リンクを作成/再利用し、トークン + URL を返す

• unpublish_file(path_or_token) — リンクを無効化（ファイルは非公開のまま）

• get_public_link(path) — パスに対する有効なリンクを取得

• list_public_links() — ユーザーの全リンクを一覧表示

セキュリティモデル

• アイデンティティ: LibreChat が注入する X-User-Id ヘッダー（{{LIBRECHAT_USER_ID}}）。プレースホルダーが未解決 → 空文字列 → フェイルクローズ。

• フェイルクローズ: ヘッダーが欠落、空、または不正な場合は HTTP 403 {"error":"missing_user_identity"} または {"error":"invalid_user_identity"} を返します。

• パスの安全性: すべてのパスは相対パスで、絶対パスと .. は拒否されます。Path.resolve() とプレフィックスチェックによりシンボリックリンクのエスケープを検出します。

• 分離: JWT の sub/id = userId により rag_api の所有者スコープを強制します（PR #319、2026-08-15 マージ）。

• 公開リンク: 不透明な secrets.token_urlsafe(16) トークンを使用し、URLにはユーザーやパスを含めません。失効は 410 Gone で行い、期限切れエントリは遅延クリーンアップされます。

開発

# Run tests
.venv/bin/pytest -q

# Lint
.venv/bin/ruff check .

# Type check (optional)
.venv/bin/mypy src/personal_files_mcp  # if mypy added to deps

ライセンス

MIT