MCP File Organizer — techblog 포스트 "MCP in Practice"용 데모

"AI 파일 정리 어시스턴트" 사용 사례를 통해 MCP를 보여주는 데모: 2개의 파일 관리 도구(list_files, move_file — read_file 없음; 서버는 파일 내용을 읽지 않고 파일 이름/확장자/수정 날짜만 읽음)를 노출하는 MCP 서버와, 사용자의 자연어 요청에 따라 어떤 도구를 호출할지 결정하는 MCP 클라이언트/에이전트(Gemini 사용, @google/genai 및 내장 MCP 지원 mcpToTool을 통해). folder는 머신의 절대 경로(데모의 storage/inbox에 국한되지 않음 — Downloads 같은 실제 폴더를 가리킬 수 있음)이며, 결과는 항상 <folder>/organized/<extension>/<year>/<month>/<day>/에 저장됩니다. 데모 데이터셋은 365일 동안 누적된 500개의 모의 파일로, 확장자별로, 그 다음 마지막 수정 날짜의 연/월/일별로 재구성됩니다.

설정

npm install

Related MCP server: Organizer MCP Server

모의 데이터 생성

npm run generate-mock   # generates 500 mock files into storage/inbox, with mtimes spread across the last 365 days

언제든지 이 명령을 다시 실행하여 새 데이터셋을 생성할 수 있습니다.

실제 에이전트 실행(Gemini API 키 필요)

client/client.ts가 실제 에이전트입니다. mcpToTool을 통해 MCP 클라이언트를 Gemini에 노출하여, 하드코딩된 규칙 없이 Gemini가 어떤 도구를 호출하고 어떤 인수를 사용할지 스스로 결정하게 합니다(자동 함수 호출). 키는 GEMINI_API_KEY, GOOGLE_API_KEY, API_KEY 순서로 읽습니다(우선순위 순). 모델은 MODEL에서 읽되 값이 gemini-로 시작하는 경우에만 사용하고, 그렇지 않으면 기본값 gemini-2.5-flash로 대체합니다.

# PowerShell
$env:GEMINI_API_KEY = "AIza..."
npm run agent

# bash
export GEMINI_API_KEY="AIza..."
npm run agent

이 변수들은 프로젝트 디렉토리의 .env 파일에도 설정할 수 있습니다. npm run agent는 .env가 존재하면 자동으로 로드합니다(Node의 --env-file-if-exists 플래그 사용).

storage/inbox 대신 실제 폴더에서 시도하려면 인수로 절대 경로를 전달하세요. 예: npm run agent -- "C:\Users\you\Downloads".

실제 데이터 사용 시 안전성

server.ts는 파일 시스템에 접근하기 전에 여러 경우를 이미 방어합니다:

• folder는 절대 경로여야 합니다 — 상대 경로는 즉시 거부되며, 서버 프로세스의 cwd 기준으로 조용히 해석되지 않습니다.

• name은 순수 파일 이름이어야 합니다(/, \, .. 없음) — folder 밖으로의 트래버설을 차단합니다.

• to_folder는 해석된 후 다시 확인되어 <folder>/organized/ 내에 머물도록 보장합니다 — ..를 통한 외부 트래버설을 차단합니다.

• move_file은 대상이 이미 존재하면 거부합니다(조용히 덮어쓰지 않음). dry_run: true를 전달하면 실제 파일을 건드리지 않고 이동될 내용을 미리 볼 수 있습니다.

• ALLOWED_ROOTS 환경 변수(절대 경로 목록, Windows에서는 ;, Unix에서는 :로 구분 — path.delimiter를 따름)를 설정하여 folder를 해당 루트로만 제한할 수 있습니다. 설정하지 않으면 데모는 원래 동작을 유지합니다: 모든 절대 폴더를 허용 — 데모 목적에는 적합하지만, 실제 데이터를 가리킬 때는 ALLOWED_ROOTS를 설정해야 합니다.

구조

server/server.ts               MCP Server: list_files, move_file — folder is any absolute path, never reads file contents
client/generate-mock-inbox.ts  Generates 500 mock files into storage/inbox
client/client.ts               MCP Client + Agent, using Gemini via @google/genai
storage/                       Generated by running generate-mock, not committed to the repo