MCP: Jak Claude inteligentnie współdziała z Twoimi lokalnymi plikami.

Model Context Protocol (MCP) zapewnia bezpieczne ramy do współpracy aplikacji z systemami plików poprzez operacje sandboxowane. Ten przewodnik wyjaśnia, jak działa MCP, omawia jego kluczowe cechy i prowadzi przez praktyczny przykład z użyciem MCP Filesystem Server.

Czym jest Model Context Protocol (MCP)?

Model Context Protocol (MCP) to zaawansowane ramy bezpieczeństwa zaprojektowane, by umożliwić kontrolowaną interakcję między aplikacjami (takimi jak asystenci AI) a systemami zewnętrznymi, w szczególności systemami plików. Działając jako bezpieczny most, MCP pozwala narzędziom na operacje takie jak odczyt, zapis czy wyszukiwanie plików w środowisku sandboxowanym, opartym na uprawnieniach.

Protokół jest szczególnie wartościowy dla deweloperów chcących zintegrować operacje na systemie plików z aplikacjami takimi jak VS Code, Claude Desktop czy innymi środowiskami programistycznymi, zachowując przy tym silne granice bezpieczeństwa.

Kluczowe cechy MCP

• Operacje sandboxowane: Wszystkie działania odbywają się w zdefiniowanych katalogach, chroniąc wrażliwe części Twojego systemu plików.
• Ustandaryzowane API: Spójny zestaw narzędzi (read_file, write_file itd.) dostępny przez jednolity interfejs.
• Bezpieczeństwo na pierwszym miejscu: Operacje ograniczone do dozwolonych katalogów z funkcjami takimi jak montowanie tylko do odczytu.
• Elastyczna integracja: Kompatybilność z różnymi środowiskami, w tym Docker, NPX, VS Code i Claude Desktop.

Wyjaśnienie MCP Filesystem Server

MCP Filesystem Server to implementacja w Node.js stworzona specjalnie do operacji na systemie plików w ramach Model Context Protocol. Dostarcza kompleksowy zestaw narzędzi do kontrolowanej pracy z plikami i katalogami.

Dostępne narzędzia w MCP Filesystem Server

Oto przegląd głównych funkcji:

• read_file: Odczyt treści pliku z użyciem kodowania UTF-8
• read_multiple_files: Przetwarzanie wielu plików jednocześnie, kontynuacja mimo pojedynczych błędów
• write_file: Tworzenie nowych plików lub nadpisywanie istniejących
• edit_file: Umożliwia selektywne edycje z dopasowaniem wzorców, w tym tryb testowy i wynik w stylu diff z Gita
• create_directory: Tworzenie katalogów z opcjonalnym tworzeniem katalogów nadrzędnych
• list_directory: Wyświetla zawartość katalogu z czytelnymi prefiksami [FILE] lub [DIR]
• move_file: Przenoszenie lub zmiana nazwy plików i katalogów
• search_files: Rekurencyjne przeszukiwanie z obsługą wzorców wykluczających
• get_file_info: Pobieranie metadanych, takich jak rozmiar, czas utworzenia i uprawnienia
• list_allowed_directories: Pokazuje wszystkie dostępne katalogi dla przejrzystości

Wszystkie te narzędzia są dostępne przez zasób file://system, który pełni rolę interfejsu do operacji MCP na systemie plików.

Korzystanie z MCP z Claude

Aby pokazać, jak MCP działa w praktyce, przejdźmy przez prawdziwy przykład użycia MCP Filesystem Server z asystentem AI Claude do wykonania typowych operacji na systemie plików.

Krok 1: Lista dozwolonych katalogów

Pierwszym krokiem było określenie, do jakich katalogów Claude ma dostęp. Skorzystaliśmy z narzędzia list_allowed_directories, które wskazało dwie dozwolone lokalizacje:

• /Users/arshia/Desktop
• /Users/arshia/Downloads

Potwierdziło to, że działania Claude’a są ograniczone tylko do tych katalogów, a reszta systemu plików pozostaje bezpieczna.

Krok 2: Przeglądanie zawartości katalogów

Następnie użyliśmy narzędzia list_directory, aby zobaczyć dostępne pliki. Wyniki były następujące:

Dla /Users/arshia/Desktop:

• [FILE] DS_Store
• [FILE] localized

Dla /Users/arshia/Downloads:

• [FILE] DS_Store
• [FILE] localized
• [DIR] Visual Studio Code.app
• [FILE] shrek.txt
• [FILE] claudes diary.pages
• [FILE] diary.pdf

To ujawniło plik shrek.txt w katalogu Downloads, a także inne pliki oraz katalog Visual Studio Code.

Zrzut ekranu przedstawiający żądania i odpowiedzi list_directory dla katalogów Desktop i Downloads

Krok 3: Próba odczytu pliku

Po zidentyfikowaniu shrek.txt spróbowaliśmy odczytać jego zawartość narzędziem read_file. Początkowo podaliśmy tylko nazwę pliku shrek.txt, zakładając, że narzędzie przeszuka dozwolone katalogi.

Skutkowało to błędem:
“Odmowa dostępu – ścieżka poza dozwolonymi katalogami: /shrek.txt nie znajduje się w /Users/arshia/Desktop, /Users/arshia/Downloads.”
Błąd pojawił się, ponieważ MCP dla bezpieczeństwa wymaga podawania pełnych ścieżek plików.

Obraz 2: Zrzut ekranu pokazujący nieudaną próbę read_file z komunikatem o błędzie

Krok 4: Udało się odczytać plik

Po poprawieniu podejścia podaliśmy pełną ścieżkę /Users/arshia/Downloads/shrek.txt do narzędzia read_file. Tym razem operacja zakończyła się sukcesem i zwróciła zawartość pliku:

Request
{
  `path`: `/Users/arshia/Downloads/shrek.txt`
}
Response

Can you see what im writing here? If you do check this out: 

⢀⡴⠑⡄⠀⠀⠀⠀⠀⠀⠀⣀⣀⣤⣤⣤⣀⡀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀ 
⠸⡇⠀⠿⡀⠀⠀⠀⣀⡴⢿⣿⣿⣿⣿⣿⣿⣿⣷⣦⡀⠀⠀⠀⠀⠀⠀⠀⠀⠀ 
⠀⠀⠀⠀⠑⢄⣠⠾⠁⣀⣄⡈⠙⣿⣿⣿⣿⣿⣿⣿⣿⣆⠀⠀⠀⠀⠀⠀⠀⠀ 
⠀⠀⠀⠀⢀⡀⠁⠀⠀⠈⠙⠛⠂⠈⣿⣿⣿⣿⣿⠿⡿⢿⣆⠀⠀⠀⠀⠀⠀⠀ 
⠀⠀⠀⢀⡾⣁⣀⠀⠴⠂⠙⣗⡀⠀⢻⣿⣿⠭⢤⣴⣦⣤⣹⠀⠀⠀⢀⢴⣶⣆ 
⠀⠀⢀⣾⣿⣿⣿⣷⣮⣽⣾⣿⣥⣴⣿⣿⡿⢂⠔⢚⡿⢿⣿⣦⣴⣾⠁⠸⣼⡿ 
⠀⢀⡞⠁⠙⠻⠿⠟⠉⠀⠛⢹⣿⣿⣿⣿⣿⣌⢤⣼⣿⣾⣿⡟⠉⠀⠀⠀⠀⠀ 
⠀⣾⣷⣶⠇⠀⠀⣤⣄⣀⡀⠈⠻⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⡇⠀⠀⠀⠀⠀⠀ 
⠀⠉⠈⠉⠀⠀⢦⡈⢻⣿⣿⣿⣶⣶⣶⣶⣤⣽⡹⣿⣿⣿⣿⡇⠀⠀⠀⠀⠀⠀ 
⠀⠀⠀⠀⠀⠀⠀⠉⠲⣽⡻⢿⣿⣿⣿⣿⣿⣿⣷⣜⣿⣿⣿⡇⠀⠀⠀⠀⠀⠀ 
⠀⠀⠀⠀⠀⠀⠀⢸⣿⣿⣷⣶⣮⣭⣽⣿⣿⣿⣿⣿⣿⣿⠀⠀⠀⠀⠀⠀⠀ 
⠀⠀⠀⠀⠀⣀⣀⣈⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⠇⠀⠀⠀⠀⠀⠀⠀ 
⠀⠀⠀⠀⠀⢿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⠃⠀⠀⠀⠀⠀⠀⠀⠀ 
⠀⠀⠀⠀⠀⠀⠹⣿⣿⣿⣿⣿⣿⣿⣿⣿⡿⠟⠁⠀⠀⠀⠀⠀⠀⠀⠀⠀ 
⠀⠀⠀⠀⠀⠀⠀⠀⠉⠛⠻⠿⠿⠿⠿⠛⠉

Shrek

• Pytanie, czy czytelnik widzi, co jest napisane
• ASCII art przedstawiający twarz Shreka
• Tekst “Shrek” na końcu

Udana operacja potwierdziła, że MCP może odczytać plik, jeśli zostanie podana poprawna ścieżka w dozwolonych katalogach.

Kluczowe wnioski z przykładu

Ten praktyczny przykład podkreśla kilka istotnych aspektów korzystania z MCP:

1. Wymagane są pełne ścieżki: Narzędzia takie jak read_file wymagają pełnych ścieżek plików, a nie tylko nazw.
2. Sandboxing działa skutecznie: Początkowa porażka pokazała, że model bezpieczeństwa MCP działa zgodnie z założeniem.
3. Iteracyjne przeszukiwanie jest najlepsze: Korzystanie z narzędzi do listowania katalogów pomaga poprawnie poruszać się po systemie plików.

Najlepsze praktyki wdrażania MCP

Na bazie naszego doświadczenia i funkcji MCP Filesystem Server zalecamy następujące dobre praktyki:

• Zawsze najpierw sprawdź uprawnienia: Użyj list_allowed_directories przed operacjami.
• Podawaj pełne ścieżki do plików: Unikniesz błędów i niejasności.
• Testuj edycje w trybie testowym: Przy edit_file przeglądaj zmiany z dryRun: true przed ich zastosowaniem.
• Planuj częściowy sukces: Narzędzia jak read_multiple_files kontynuują nawet przy pojedynczych błędach.
• Stosuj zasadę najmniejszych uprawnień: Przy konfiguracji serwera używaj montowań tylko do odczytu dla katalogów, których nie należy modyfikować.

Podsumowanie

Model Context Protocol (MCP) i jego Filesystem Server zapewniają solidne, bezpieczne podejście do operacji na systemie plików w kontrolowanych środowiskach. Nasz przykład z Claude’em pokazuje praktyczne użycie narzędzi takich jak list_directory i read_file, a także podkreśla ważne zasady, jak stosowanie pełnych ścieżek i rozumienie granic uprawnień.

Stosując przedstawione tu dobre praktyki, możesz skutecznie i bezpiecznie integrować operacje na systemie plików z Twoimi aplikacjami lub workflow deweloperskimi.

Dla deweloperów chcących wdrożyć MCP w swoich projektach, oficjalna dokumentacja na GitHubie zawiera szczegółowe informacje i przewodniki wdrożeniowe.