librechat-personal-files-mcp

LibreChat 에이전트를 위한 사용자별 개인 파일 저장소, 영구 문서, RAG 인덱싱/검색, 그리고 불투명한 공개 링크 게시를 제공하는 MCP 서버입니다.

기능

• 사용자별 저장소: /data/private/<userId>/ 아래의 개인 파일에 대한 전체 CRUD, 목록, 이동 작업을 제공합니다.

• 문서 카탈로그: save_documentation / update_documentation은 docs/에 저장하고 memory-index.json(스키마 v2)을 업데이트합니다.

• RAG 통합: index_document는 canary 검증(issue #305)을 통해 POST /embed로 콘텐츠를 rag_api에 전송합니다. search_knowledge는 의미 검색을, remove_from_knowledge는 삭제를 담당합니다.

• 공개 게시: publish_file은 암호학적으로 무작위한 토큰(≥128비트)을 생성합니다. 파일은 Nginx X-Accel-Redirect를 통해 Content-Disposition: attachment, nosniff, no-store로 제공됩니다.

• 엄격한 보안: X-User-Id가 없거나 유효하지 않으면 fail-closed 처리됩니다. 경로 탐색 차단, 절대 경로 금지, .. 세그먼트 금지, 심볼릭 링크 이탈 감지, 예약 세그먼트 보호, 프로세스 간 잠금을 통한 원자적 인덱스 쓰기를 지원합니다.

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의 블록을 기존 override 파일에 복사하세요.

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) — 임베딩 + canary 검증, 인덱스 상태 업데이트

• 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() — 사용자의 모든 링크

보안 모델

• 신원: X-User-Id 헤더는 LibreChat이 주입합니다 ({{LIBRECHAT_USER_ID}}). 플레이스홀더가 해석되지 않음 → 빈 문자열 → fail-closed.

• Fail-closed: 헤더가 없거나 비어 있거나 유효하지 않으면 → 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