MCP File Organizer — демо для поста в техблоге «MCP in Practice»

Демо, иллюстрирующее MCP на примере сценария «AI-ассистент для организации файлов»: MCP-сервер, предоставляющий 2 инструмента управления файлами (list_files, move_file — без read_file; сервер никогда не читает содержимое файлов, только имя/расширение/дату изменения), и MCP-клиент/агент, использующий Gemini (через @google/genai, со встроенной поддержкой MCP через mcpToTool) для решения, какой инструмент вызвать на основе запроса пользователя на естественном языке. folder — это любой абсолютный путь на машине (не ограниченный демонстрационным storage/inbox — он может указывать на реальную папку, например Downloads), а результаты всегда попадают в <folder>/organized/<extension>/<year>/<month>/<day>/. Демонстрационный набор данных — 500 тестовых файлов, накопленных за 365 дней, реорганизованных по расширению, а затем по году/месяцу/дню последнего изменения.

Установка

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

Повторно запустите эту команду в любое время, чтобы сгенерировать свежий набор данных.

Запуск реального агента (требуется API-ключ Gemini)

client/client.ts — это реальный агент: он предоставляет MCP-клиент Gemini через mcpToTool, позволяя 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\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