Agente de sistema de archivos MCP

Un asistente local agéntico de sistema de archivos construido con LangChain, Ollama, FastMCP y MCP.

El proyecto demuestra cómo un LLM puede seleccionar y usar autónomamente herramientas expuestas por un servidor MCP para realizar operaciones relacionadas con archivos, como leer, listar, escribir y buscar archivos.

Arquitectura

                         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

Características

• Arquitectura de herramientas basada en MCP

• Servidor FastMCP local usando transporte HTTP

• Agente LangChain con llamada a herramientas

• Inferencia LLM local a través de Ollama

• Lectura de archivos PDF

• Lectura y escritura de archivos DOCX

• Listado de archivos con filtro por extensión

• Búsqueda dentro de archivos PDF y DOCX

• Estado de conversación usando checkpointing de LangGraph

• Selección automática de herramientas por el LLM

Stack Tecnológico

• Python

• LangChain

• LangGraph

• Ollama

• Qwen3 1.7B

• FastMCP

• Model Context Protocol (MCP)

• langchain-mcp-adapters

• PyPDF

• python-docx

Estructura del Proyecto

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

Instalación

1. Clonar el repositorio

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

2. Instalar dependencias de Python

pip install -r requirements.txt

3. Instalar Ollama

Instala Ollama desde el sitio web oficial y asegúrate de que se esté ejecutando localmente.

Luego descarga el modelo:

ollama pull qwen3:1.7b

Puedes verificar que el modelo está disponible con:

ollama list

Ejecución del Proyecto

El proyecto usa dos procesos porque el servidor MCP se comunica con el cliente a través de HTTP.

Terminal 1 — Iniciar el servidor MCP

Ejecuta este comando desde la raíz del proyecto:

python fs_mcp.py

El servidor debería estar disponible en:

http://127.0.0.1:8000/mcp

Terminal 2 — Iniciar el agente

Abre otra terminal en la raíz del proyecto:

python main.py

Luego puedes ingresar solicitudes como:

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

o:

List all PDF files in the tests folder.

o:

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

Ejemplo de Flujo del Agente

Para una solicitud como:

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

el agente realiza lo siguiente:

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

Requisitos

Se recomienda Python 3.11+.

Ollama debe estar instalado y ejecutándose localmente.

El modelo Qwen debe estar disponible:

ollama pull qwen3:1.7b

También puedes usar un modelo a través de un proveedor de inferencia.

Dependencias

Las dependencias directas del proyecto son:

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

Mejoras Futuras

• Agregar soporte para más formatos de archivo

• Agregar herramientas de eliminación de archivos y creación de directorios

• Agregar validación de rutas y sandboxing más sólidos

• Agregar autenticación para servidores MCP remotos

• Agregar respuestas en streaming

• Agregar análisis de documentos más enriquecido

• Agregar almacenamiento persistente de conversaciones

• Agregar servidores MCP adicionales para bases de datos, GitHub o búsqueda web

• Mejorar la confiabilidad de la selección de herramientas con modelos locales más grandes

Objetivos de Aprendizaje

Este proyecto demuestra la interacción entre:

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

Está pensado como un ejemplo práctico de construcción de una aplicación agéntica con Model Context Protocol (MCP) y LLMs alojados localmente.