Baomihua Formatter MCP Server

OpenList 및 CloudDrive2의 미디어 파일을 검사하고 조작하며, TMDB 영화 및 TV 메타데이터를 조회하기 위한 독립형 Node.js MCP 서버입니다. 이 서버는 MCP stdio를 통해 통신하며 스토리지/TMDB 자격 증명을 도구 설명이나 커밋된 문서가 아닌 로컬 환경 구성에 보관합니다.

요구 사항

• Node.js 20 이상 (package.json은 engines.node >=20.0.0을 선언합니다).

• 해당 백엔드를 사용할 때 구성된 OpenList 및/또는 CloudDrive2 엔드포인트에 대한 네트워크 액세스.

• TMDB 도구를 사용할 때 TMDB 자격 증명.

설치

서버 프로젝트 디렉터리에서:

Set-Location C:\path\to\baomihua-formatter-mcp-server
Copy-Item .env.example .env
npm install

환경에 필요한 엔드포인트와 자격 증명으로 로컬 .env를 편집하세요. .env는 Git에서 무시됩니다. 절대 커밋하지 말고, 이 README에 비밀을 붙여넣지 말며, 소스 제어에 커밋된 MCP 클라이언트 구성에 실제 자격 증명을 포함하지 마세요.

지원되는 구성 키는 .env.example에 문서화되어 있으며, 다음을 포함합니다:

• OPENLIST_URL, OPENLIST_USERNAME, OPENLIST_PASSWORD 및 선택적 OPENLIST_OTP_CODE;

• CLOUDDRIVE2_URL, CLOUDDRIVE2_TOKEN 및 CLOUDDRIVE2_TLS;

• TMDB_API_KEY 또는 TMDB_TOKEN, 추가로 선택적 TMDB_LANGUAGE 및 TMDB_PROXY;

• STORAGE_CONCURRENCY, UPLOAD_CONCURRENCY 및 STORAGE_MAX_CONCURRENCY;

MCP 서버 실행

npm 스크립트가 stdio 서버를 시작합니다:

npm run mcp

이 프로세스는 MCP 클라이언트에 의해 시작되도록 설계되었으므로 일반 프로토콜 트래픽은 stdin/stdout을 통해 전송됩니다. 서버를 임베드할 때 진단 출력을 stdout에 남기지 마세요.

일반 MCP 클라이언트 항목

절대 Node 실행 파일 경로와 절대 서버 경로를 사용하세요. 예제 경로만 바꾸고 비밀은 서버의 로컬 .env를 통해 구성하세요. 이 항목에는 의도적으로 자격 증명이 포함되어 있지 않습니다:

{
  "mcpServers": {
    "baomihua-formatter": {
      "command": "C:\\Program Files\\nodejs\\node.exe",
      "args": [
        "C:\\path\\to\\baomihua-formatter-mcp-server\\server.js"
      ]
    }
  }
}

MCP 클라이언트는 서버 프로젝트의 .env 파일이 있는 컨텍스트에서 항목을 시작해야 합니다. 동등한 셸 명령은 다음과 같습니다:

& 'C:\Program Files\nodejs\node.exe' 'C:\path\to\baomihua-formatter-mcp-server\server.js'

도구 그룹 및 동작 방식

스토리지 탐색

두 스토리지 백엔드 모두 직접 목록 조회와 재귀 스캔을 제공합니다:

• openlist_list / clouddrive2_list는 직계 하위 항목만 나열합니다.

• openlist_scan / clouddrive2_scan은 하위 항목을 재귀적으로 수집하며 제한된 concurrency 및 continue_on_error 옵션을 허용합니다.

• openlist_stat / clouddrive2_stat은 정확히 하나의 경로를 검사합니다.

• openlist_search / clouddrive2_search는 경로 아래의 항목을 검색합니다.

스캔 및 업로드 디렉터리 작업은 제한된 동시성을 사용합니다. 동시성을 서버의 구성된 최대값 이내로 유지하고, 부분 완료를 의도적으로 수용하지 않는 한 continue_on_error를 false로 두세요.

파일 작업

OpenList와 CloudDrive2는 각각 디렉터리 생성, 이름 변경, 파일/디렉터리 삭제, 이동, 복사 및 파일/디렉터리 업로드를 위한 도구를 제공합니다. CloudDrive2는 또한 clouddrive2_get_download_url을 제공합니다.

모든 변경 도구는 confirm: true를 요구합니다. Agent 또는 MCP 클라이언트는 먼저 정확한 제안 경로, 이름, 대상, 충돌 정책 및 파괴적 영향을 사용자에게 제시해야 합니다. 서버는 확인되지 않은 변경을 거부합니다. continue_on_error는 확인 메커니즘이 아닙니다. 항목이 실패한 후 제한된 배치가 계속될지 여부만 제어합니다.

TMDB

서버는 tmdb_search_movie, tmdb_search_tv, tmdb_get_movie_details, tmdb_get_tv_details 및 tmdb_get_season_details를 제공합니다. 이 도구들은 후보 또는 메타데이터를 반환하며 파일 이름을 변경하지 않습니다.

파일 이름에서 제목/연도/시즌/에피소드/화질 추출은 의도적으로 Agent의 책임입니다. 미디어 포맷팅 워크플로우의 경우 전체 스토리지 경로를 검사하고, 해당 필드를 독립적으로 추출하며, TMDB 후보를 조회하고, 세부 정보로 선택한 결과를 검증한 후, 변경을 제안하기 전에 사용자에게 모호한 동명 후보를 해결하도록 요청하세요.

권장 워크플로우

1. 직접 탐색에는 백엔드 *_list 호출을, 재귀 수집에는 *_scan을 사용하세요.

2. 원본 경로를 유지하고 제목, 연도, 시즌, 에피소드, 화질 및 자막 마커를 독립적으로 파싱하세요.

3. TMDB를 검색하고, 파싱된 증거와 후보를 비교하며, 선택한 ID의 세부 정보를 가져오세요.

4. 완전한 이름 변경/이동/복사/삭제/업로드 제안을 표시하고 명시적 확인을 기다리세요.

5. confirm: true로 확인된 변경을 실행하세요.

6. 후속 목록, stat 또는 스캔으로 검증하고 성공, 건너뜀 및 오류를 보고하세요.

개발

이 디렉터리에서 테스트 스위트를 실행하세요:

npm test

이 프로젝트는 비공개이며 ESM을 사용하고 이전 formatter CLI에 대한 런타임 의존성이 없습니다. 자격 증명과 생성된 로그를 커밋에 포함하지 마세요.