MCP File System Agent

Локальный агентный файловый ассистент, созданный с использованием LangChain, Ollama, FastMCP и MCP.

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

Архитектура

                         User
                           │
                           ▼
                  ┌─────────────────┐
                  │  LangChain      │
                  │     Agent       │
                  └────────┬────────┘
                           │
                           ▼
                  ┌─────────────────┐
                  │   Ollama LLM    │
                  │   Qwen3 1.7B    │
                  └────────┬────────┘
                           │
                    Tool selection
                           │
                           ▼
                ┌──────────────────────┐
                │ LangChain MCP Adapter│
                └──────────┬───────────┘
                           │
                       MCP / HTTP
                           │
                           ▼
                ┌──────────────────────┐
                │     FastMCP Server   │
                │   localhost:8000/mcp │
                └──────────┬───────────┘
                           │
             ┌─────────────┼─────────────┐
             ▼             ▼             ▼
        read_file     list_files    write_file
             │
             ▼
       Local File System

Related MCP server: local-mcp

Возможности

• Архитектура инструментов на основе MCP

• Локальный FastMCP-сервер с HTTP-транспортом

• Агент LangChain с вызовом инструментов

• Локальный вывод LLM через Ollama

• Чтение PDF-файлов

• Чтение и запись DOCX-файлов

• Просмотр списка файлов с фильтрацией по расширению

• Поиск внутри PDF- и DOCX-файлов

• Состояние диалога с использованием контрольных точек LangGraph

• Автоматический выбор инструментов LLM

Технологический стек

• Python

• LangChain

• LangGraph

• Ollama

• Qwen3 1.7B

• FastMCP

• Model Context Protocol (MCP)

• langchain-mcp-adapters

• PyPDF

• python-docx

Структура проекта

MCP/
│
├── tests/
│   └── sample.docx
│
├── fs_mcp.py
├── main.py
├── requirements.txt
└── README.md

Установка

1. Клонируйте репозиторий

git clone https://github.com/jibixn/File-System-Tools-MCP
cd MCP

2. Установите зависимости Python

pip install -r requirements.txt

3. Установите Ollama

Установите Ollama с официального сайта и убедитесь, что он запущен локально.

Затем загрузите модель:

ollama pull qwen3:1.7b

Вы можете проверить, что модель доступна, с помощью:

ollama list

Запуск проекта

Проект использует два процесса, поскольку MCP-сервер взаимодействует с клиентом по HTTP.

Терминал 1 — Запустите MCP-сервер

Выполните эту команду из корня проекта:

python fs_mcp.py

Сервер должен быть доступен по адресу:

http://127.0.0.1:8000/mcp

Терминал 2 — Запустите агента

Откройте другой терминал в корне проекта:

python main.py

Затем вы можете вводить запросы, например:

Read the file in tests folder named sample.docx and provide me the summary.

или:

List all PDF files in the tests folder.

или:

Write "Hello, World!" to tests/output.docx.

Пример потока работы агента

Для такого запроса, как:

Read the file in tests folder named sample.docx and provide me the summary.

агент выполняет следующее:

User request
     │
     ▼
LLM analyzes request
     │
     ▼
LLM selects read_file
     │
     ▼
LangChain MCP Adapter
     │
     ▼
MCP HTTP request
     │
     ▼
FastMCP read_file()
     │
     ▼
python-docx reads file
     │
     ▼
Tool result returned to agent
     │
     ▼
LLM summarizes content
     │
     ▼
Final response

Требования

Рекомендуется Python 3.11+.

Ollama должен быть установлен и запущен локально.

Модель Qwen должна быть доступна:

ollama pull qwen3:1.7b

Вы также можете использовать модель через провайдера вывода.

Зависимости

Прямые зависимости проекта:

fastmcp==3.4.7
langchain==1.3.14
langchain-mcp-adapters==0.3.2
langchain-ollama==1.1.0
langgraph-checkpoint==4.2.0
pypdf==6.14.2
python-docx==1.2.0

Будущие улучшения

• Добавить поддержку дополнительных форматов файлов

• Добавить инструменты удаления файлов и создания каталогов

• Добавить более строгую проверку путей и песочницу

• Добавить аутентификацию для удаленных MCP-серверов

• Добавить потоковые ответы

• Добавить более полный разбор документов

• Добавить постоянное хранение диалогов

• Добавить дополнительные MCP-серверы для баз данных, GitHub или веб-поиска

• Повысить надежность выбора инструментов с помощью более крупных локальных моделей

Учебные цели

Этот проект демонстрирует взаимодействие между:

LLM
 ↓
LangChain Agent
 ↓
Tool Calling
 ↓
MCP Client
 ↓
MCP Protocol
 ↓
FastMCP Server
 ↓
Python Functions

Он задуман как практический пример создания агентного приложения с Model Context Protocol (MCP) и локально размещенными LLM.