MCP на практике: подключаем файлы и браузер к AI-ассистенту

Что получится в конце

Мы подключим к совместимому AI-клиенту два локальных MCP-сервера:

• filesystem — читает и изменяет файлы только внутри каталога mcp-lab/workspace;
• playwright — открывает страницы в отдельной браузерной сессии без ваших сохранённых паролей, cookies и активных аккаунтов.

После настройки выполним две задачи с заранее известным результатом:

1. ассистент прочитает тестовый файл, создаст сводку и затем проверит записанное содержимое;
2. браузер откроет страницу example.com и извлечёт из неё три проверяемых значения.

AI-клиент
├── MCP filesystem
│   └── доступ только к /абсолютный/путь/mcp-lab/workspace
└── MCP playwright
    └── отдельный изолированный профиль браузера

Модель не читает диск и не управляет браузером напрямую. Она использует вызов инструментов: запрашивает конкретную операцию, MCP-клиент передаёт её серверу, а сервер возвращает структурированный результат.

Конкретный кейс: проверка материалов перед публикацией

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

Без интеграции модель видит только текст, который пользователь вручную вставил в чат. Если выдать ей полный доступ к компьютеру, ошибка в запросе может затронуть документы, ключи доступа или чужой проект. MCP позволяет поставить между моделью и системой контролируемую границу:

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

Эта схема подходит не только редакции. Тем же способом можно безопаснее разбирать отчёты, проверять локальную документацию, заполнять тестовую форму или собирать данные с доступной пользователю страницы.

Что понадобится

Для лабораторной работы нужны:

• AI-клиент с поддержкой локальных MCP-серверов;
• Node.js 18 или новее вместе с командой npm;
• терминал и текстовый редактор;
• около 500 МБ свободного места для пакетов и браузера Chromium;
• доступ к интернету во время установки и второй проверки.

Проверьте Node.js и npm:

node --version
npm --version

Первая команда должна вывести версию не ниже v18, вторая — номер версии npm. Если команда не найдена, сначала установите актуальную LTS-версию Node.js, затем закройте и заново откройте терминал.

В статье используется универсальная JSON-структура mcpServers. Её понимают многие настольные AI-клиенты. Некоторые редакторы называют корневой объект servers, а Codex использует TOML. Соответствующие варианты приведены ниже.

Шаг 1. Создайте изолированную лабораторию

Не указывайте в файловой конфигурации домашний каталог, корень диска или папку со всеми проектами. Создайте отдельный каталог без секретов.

macOS и Linux:

mkdir -p "$HOME/mcp-lab/runtime"
mkdir -p "$HOME/mcp-lab/workspace/inbox"
mkdir -p "$HOME/mcp-lab/workspace/outbox"
cd "$HOME/mcp-lab/runtime"
npm init -y

Windows PowerShell:

New-Item -ItemType Directory -Force "$HOME\mcp-lab\runtime"
New-Item -ItemType Directory -Force "$HOME\mcp-lab\workspace\inbox"
New-Item -ItemType Directory -Force "$HOME\mcp-lab\workspace\outbox"
Set-Location "$HOME\mcp-lab\runtime"
npm init -y

Каталоги выполняют разные роли:

• runtime содержит установленные MCP-пакеты и файл фиксации версий;
• workspace — единственная область, которую увидит файловый сервер;
• inbox хранит исходные материалы;
• outbox принимает результаты.

Такое разделение не является полноценной allowlist-политикой операционной системы, но резко сокращает область возможной ошибки.

Шаг 2. Установите серверы и браузер

Находясь в каталоге mcp-lab/runtime, установите файловый MCP-сервер, Playwright MCP и браузерную зависимость:

npm install @modelcontextprotocol/server-filesystem @playwright/mcp @playwright/test
npx playwright install chromium

В Linux установка Chromium иногда сообщает о недостающих системных библиотеках. Если у вас есть административные права, можно использовать:

npx playwright install --with-deps chromium

Не запускайте эту команду автоматически на рабочем сервере: параметр --with-deps может устанавливать системные пакеты. Сначала посмотрите, какие изменения предлагает менеджер пакетов.

Проверьте, что локальные команды доступны:

npx --no-install mcp-server-filesystem --help
npx --no-install playwright-mcp --help

Справка может завершиться после вывода параметров — это нормально. Важно, чтобы не появлялись сообщения package not found или could not determine executable.

Файл package-lock.json, созданный npm, фиксирует дерево зависимостей. Сохраните его вместе с конфигурацией лаборатории. После успешной проверки для повторной установки используйте npm ci, а не обновление всех пакетов до произвольных новых версий.

Шаг 3. Узнайте абсолютные пути

MCP-сервер запускается отдельным процессом и не обязан знать текущую папку вашего проекта. Поэтому в конфигурации нужны абсолютные пути.

macOS и Linux:

cd "$HOME/mcp-lab/runtime"
pwd
cd "$HOME/mcp-lab/workspace"
pwd

Windows PowerShell:

Resolve-Path "$HOME\mcp-lab\runtime"
Resolve-Path "$HOME\mcp-lab\workspace"

Скопируйте оба результата. Далее используются условные значения:

/Users/anna/mcp-lab/runtime
/Users/anna/mcp-lab/workspace

Замените их своими путями. Не оставляйте $HOME, ~ или ${workspaceFolder}, если документация конкретного клиента прямо не обещает их подстановку.

Шаг 4. Добавьте стандартную MCP-конфигурацию

Откройте настройки MCP в вашем AI-клиенте и добавьте следующую конфигурацию. Замените оба пути на абсолютные значения из предыдущего шага.

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "--no-install",
        "@modelcontextprotocol/server-filesystem",
        "/Users/anna/mcp-lab/workspace"
      ],
      "cwd": "/Users/anna/mcp-lab/runtime"
    },
    "playwright": {
      "command": "npx",
      "args": [
        "--no-install",
        "@playwright/mcp",
        "--isolated",
        "--headless"
      ],
      "cwd": "/Users/anna/mcp-lab/runtime"
    }
  }
}

Назначение параметров:

• --no-install запрещает npx незаметно скачивать новую версию при каждом запуске;
• последний аргумент файлового сервера задаёт единственный разрешённый каталог;
• cwd направляет npx в папку с локально установленными пакетами;
• --isolated создаёт отдельную браузерную сессию;
• --headless запускает браузер без отдельного окна.

Во время первой диагностики можно временно убрать --headless. Тогда вы увидите действия браузера. После проверки верните параметр, если видимое окно не требуется.

На Windows клиент может ожидать исполняемый файл npx.cmd. Если npx не запускается, замените только поле команды:

"command": "npx.cmd"

Обратные слеши в JSON необходимо удваивать:

"cwd": "C:\\Users\\Anna\\mcp-lab\\runtime"

Вариант для Codex

Если клиент хранит MCP-настройки в TOML, эквивалентная конфигурация выглядит так:

[mcp_servers.filesystem]
command = "npx"
args = [
  "--no-install",
  "@modelcontextprotocol/server-filesystem",
  "/Users/anna/mcp-lab/workspace"
]
cwd = "/Users/anna/mcp-lab/runtime"

[mcp_servers.playwright]
command = "npx"
args = [
  "--no-install",
  "@playwright/mcp",
  "--isolated",
  "--headless"
]
cwd = "/Users/anna/mcp-lab/runtime"

Для клиента с корневым объектом servers сохраните содержимое двух серверов, но замените только первую строку JSON:

{
  "servers": {
    "filesystem": {
      "...": "те же поля command, args и cwd"
    },
    "playwright": {
      "...": "те же поля command, args и cwd"
    }
  }
}

Не вставляйте многоточия в настоящую конфигурацию: этот фрагмент показывает только различие схем.

Шаг 5. Перезапустите клиент и проверьте соединение

Полностью закройте AI-клиент и откройте его снова. Простого создания нового чата иногда недостаточно: MCP-процессы запускаются вместе с приложением.

В панели инструментов или MCP-диагностике должны появиться два подключённых сервера. У файлового сервера обычно доступны операции чтения, поиска, записи, редактирования и просмотра разрешённых каталогов. У Playwright — навигация, снимок структуры страницы, клики и чтение текста.

Первую проверку выполните без изменения файлов:

Используй только сервер filesystem. Вызови инструмент просмотра разрешённых каталогов и сообщи единственный доступный корневой путь. Ничего не создавай и не изменяй.

Успешный результат — ассистент показывает только путь mcp-lab/workspace. Домашняя папка, runtime и корень диска появляться не должны.

Если клиент просит подтвердить вызов, проверьте имя инструмента и аргументы. Для начала оставьте подтверждение включённым. Контур подтверждения особенно важен для записи, перемещения и удаления файлов.

Проверка № 1: чтение и запись локального файла

Создайте фиксированный входной файл. На macOS и Linux:

cd "$HOME/mcp-lab/workspace"
printf 'project=Atlas\nstage=verification\nowner=editor\n' > inbox/task.txt

Windows PowerShell:

@(
  "project=Atlas"
  "stage=verification"
  "owner=editor"
) | Set-Content -Encoding utf8 "$HOME\mcp-lab\workspace\inbox\task.txt"

Отправьте ассистенту точную задачу, подставив абсолютный путь к workspace:

Используй только инструменты сервера filesystem. Прочитай файл /Users/anna/mcp-lab/workspace/inbox/task.txt. Создай файл /Users/anna/mcp-lab/workspace/outbox/summary.txt ровно с двумя строками: первая — Проект: Atlas, вторая — Этап: verification. Не добавляй заголовок, маркеры или пояснения. После записи снова прочитай созданный файл и сравни его с требуемым текстом.

Здесь проверяется полная цепочка: модель выбирает инструменты, файловый сервер читает вход, выполняет запись в разрешённом каталоге и возвращает результат повторного чтения.

Независимая проверка

Не ограничивайтесь сообщением ассистента «готово». Откройте файл обычной командой:

macOS и Linux:

cat "$HOME/mcp-lab/workspace/outbox/summary.txt"

Windows PowerShell:

Get-Content "$HOME\mcp-lab\workspace\outbox\summary.txt"

Ожидаемое содержимое:

Проект: Atlas
Этап: verification

Для строгой проверки без визуального сравнения выполните из каталога runtime:

node -e "const fs=require('fs');const p='../workspace/outbox/summary.txt';const s=fs.readFileSync(p,'utf8').replace(/\r\n/g,'\n').trimEnd();const e='Проект: Atlas\nЭтап: verification';if(s!==e){console.error('FAIL:',JSON.stringify(s));process.exit(1)}console.log('PASS: summary.txt совпадает')"

Сообщение PASS подтверждает результат. Если команда выводит FAIL, сравните пробелы, дополнительные строки и кодировку.

Проверка границы файлового доступа

Теперь убедитесь, что ограничение работает не только на бумаге. Попросите ассистента выполнить безопасное чтение заведомо внешнего файла:

Используй filesystem и попробуй получить метаданные файла package.json из каталога mcp-lab/runtime. Не меняй файл. Покажи ответ инструмента дословно, но не повторяй содержимое других файлов.

Ожидается отказ, потому что runtime расположен вне разрешённого workspace. Формулировка ошибки зависит от версии сервера, поэтому проверяйте смысл: операция должна быть отклонена как выход за разрешённые каталоги.

Если ассистент прочитал файл, остановитесь и исправьте конфигурацию. Вероятные причины:

• файловому серверу передан каталог mcp-lab, а не mcp-lab/workspace;
• клиент использует другую копию конфигурации;
• старый MCP-процесс остался запущен после изменения настроек;
• клиент самостоятельно предоставил серверу более широкие roots.

Проверка № 2: браузерная задача

Для повторяемой проверки используется демонстрационный домен https://example.com/. На странице есть стабильные элементы: заголовок документа, заголовок первого уровня и одна ссылка.

Отправьте задачу:

Используй только инструменты сервера playwright. Открой https://example.com/. Не переходи по ссылкам и ничего не скачивай. Верни три строки: Title: с заголовком вкладки, H1: с текстом первого заголовка и Link: с абсолютным адресом единственной ссылки. Получи данные из фактически открытой страницы, не отвечай по памяти.

Ожидаемые первые две строки:

Title: Example Domain
H1: Example Domain

Строка Link: должна содержать абсолютный HTTPS-адрес, полученный со страницы. Не фиксируйте успех только по совпадению известного текста: в журнале вызовов должен быть виден переход браузера на заданный URL и чтение структуры страницы.

Дополнительно попросите:

Покажи текущий URL браузерной вкладки и закрой вкладку. Не открывай новые страницы.

Так вы проверите управление состоянием браузера и завершите тестовую сессию.

Как понять, что конфигурация действительно работает

Рабочая настройка должна пройти все пункты:

• клиент показывает серверы filesystem и playwright как подключённые;
• список разрешённых каталогов содержит только workspace;
• ассистент прочитал inbox/task.txt через файловый инструмент;
• outbox/summary.txt существует и проходит независимую Node.js-проверку;
• чтение файла из runtime отклонено;
• Playwright фактически открыл https://example.com/;
• заголовок вкладки и H1 совпали с ожидаемыми значениями;
• основной пользовательский профиль браузера не подключался.

Ответ модели без записанного файла или без видимого вызова браузерного инструмента не считается успешным тестом. Галлюцинация модели может выглядеть убедительно, особенно когда содержимое известной страницы легко угадать.

Что чаще всего ломается

Сервер отображается как disconnected

Запустите команды справки вручную из runtime. Если они работают в терминале, но не в клиенте, проверьте cwd, абсолютный путь к npx и журнал запуска MCP. Графическое приложение может получать другой набор переменных окружения, чем терминал.

Клиент не понимает поле cwd

Некоторые клиенты не поддерживают рабочий каталог процесса. В этом случае укажите абсолютный путь к исполняемому JavaScript-файлу пакета либо установите пакеты в каталог, который клиент использует как рабочий. Не возвращайтесь к @latest только ради обхода ошибки: это ухудшает повторяемость.

Файловый сервер сообщает, что каталог не существует

Путь проверяется при запуске. Создайте каталог заранее, исправьте регистр букв и перезапустите клиент. На Windows используйте реальный абсолютный путь и двойные обратные слеши в JSON.

Ассистент не видит файл

Сначала вызовите просмотр разрешённых каталогов, затем список содержимого inbox. Частая причина — файл создан в похожей папке другого пользователя или конфигурация указывает старый путь.

Chromium не запускается

Повторите npx playwright install chromium из runtime. В Linux проверьте сообщение о системных библиотеках. На сервере без графической среды оставьте --headless.

Браузер открывается, но страница недоступна

Проверьте адрес обычным браузером и убедитесь, что корпоративный proxy или firewall не блокирует процесс Node.js. Ошибка сети не означает неисправность MCP.

Модель отвечает без инструментов

Явно назовите сервер, потребуйте получить данные с фактически открытой страницы и проверьте, разрешены ли инструменты в текущем режиме клиента. Одного знания URL недостаточно.

После обновления всё перестало работать

Верните сохранённые package.json и package-lock.json, удалите только каталог зависимостей лаборатории и выполните npm ci. Не удаляйте пользовательские проекты или домашний каталог.

Безопасность файлового инструмента

Ограничение каталогом защищает файлы снаружи, но внутри workspace сервер может иметь инструменты записи, перемещения и удаления. Поэтому:

• не помещайте в лабораторию ключи API, SSH-ключи, пароли и резервные копии;
• не подключайте весь домашний каталог ради удобства;
• держите подтверждение для изменяющих операций включённым;
• храните важные материалы в системе контроля версий или делайте резервную копию;
• перед выполнением проверяйте путь назначения и имя инструмента;
• для рабочих данных создавайте отдельные каталоги чтения и результатов;
• не считайте текстовое обещание «ничего не удалять» заменой техническим ограничениям.

Файловый сервер ограничивает пути, но не превращает разрешённый каталог в read-only. Если необходима строгая защита от записи, запускайте сервер в контейнере с read-only mount или используйте права операционной системы.

Безопасность браузерного инструмента

Веб-страница является недоверенным вводом. Она может содержать скрытую или видимую prompt injection — текст, который пытается заставить ассистента игнорировать задачу, открыть локальный файл или отправить данные на другой сайт.

Практические ограничения:

• не подключайте основной профиль Chrome к первой конфигурации;
• не входите через изолированный браузер в почту, банк или административную панель во время теста;
• задавайте список допустимых доменов в самом задании и проверяйте переходы;
• не разрешайте скачивание и запуск файлов без отдельного решения пользователя;
• не копируйте на страницу содержимое локальных документов;
• отделяйте чтение страницы от отправки формы или публикации;
• закрывайте сессию после работы с чувствительными данными.

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

Почему не стоит использовать @latest в рабочей конфигурации

Команда вида npx @playwright/mcp@latest удобна для быстрого знакомства, но при следующем запуске может загрузить другую версию. Тогда набор инструментов, параметры запуска или поведение браузера изменятся без правки вашей конфигурации.

В лаборатории пакеты устанавливаются локально, версии записываются в package-lock.json, а MCP запускается с --no-install. Для воспроизведения на другом компьютере достаточно скопировать:

• package.json;
• package-lock.json;
• MCP-конфигурацию без персональных путей;
• описание двух проверочных задач.

На новом компьютере создайте те же каталоги, выполните npm ci, установите Chromium и подставьте новые абсолютные пути.

Ограничения решения

• Это локальная конфигурация. Она не описывает удалённый MCP-сервер, TLS, сетевую авторизацию и нескольких пользователей.
• Разрешённый каталог доступен процессу с правами текущего пользователя. MCP не заменяет права файловой системы и контейнерную изоляцию.
• Файловые инструменты могут изменять данные. Для строгого режима чтения нужны дополнительные ограничения.
• Браузер имеет сетевой доступ. Изоляция профиля не является сетевой песочницей.
• Интерфейсы клиентов различаются. Имя файла конфигурации, корневой объект и политика подтверждений зависят от приложения.
• Веб-страницы меняются. При изменении демонстрационного домена обновите ожидаемые значения, но не принимайте ответ модели без фактического вызова инструмента.
• MCP не определяет бизнес-политику. Протокол передаёт описание и результаты инструментов, а разрешения задают клиент, сервер и операционная система.
• Тест не проверяет производительность. Он подтверждает соединение, границы доступа и базовое выполнение двух задач.

Итоговый чек-лист

• Node.js и npm доступны из среды AI-клиента.
• MCP-пакеты установлены локально в runtime.
• package-lock.json сохранён.
• В конфигурации используются абсолютные пути.
• Filesystem видит только workspace.
• Playwright запускается с --isolated.
• Запись summary.txt проверена независимой командой.
• Попытка чтения из runtime отклонена.
• Браузерная задача подтверждена журналом вызовов.
• Изменяющие действия требуют подтверждения.
• В разрешённой папке нет секретов и ценных оригиналов.

Что вы теперь умеете

У вас есть минимальная рабочая MCP-конфигурация с двумя разными границами доверия. Файловый сервер ограничен отдельной лабораторной папкой, а браузер работает в изолированной сессии. Обе интеграции проверяются не обещанием ассистента, а наблюдаемым результатом: точным содержимым файла, отказом за пределами каталога и данными реально открытой страницы.

Следующий шаг — перенести схему на собственную задачу, сохранив те же принципы: минимальный доступ, фиксированные версии, подтверждение изменений и независимая проверка результата.

← Все практические гайды · Лабораторный глоссарий →