# MCP File System Agent

[![M8ven Score](https://m8ven.ai/badge/mcp/jibixn-file-system-tools-mcp-141j2v)](https://m8ven.ai/mcp/jibixn-file-system-tools-mcp-141j2v)

A local **agentic file-system assistant** built with **LangChain, Ollama, FastMCP, and MCP**.

The project demonstrates how an LLM can autonomously select and use tools exposed by an MCP server to perform file-related operations such as reading, listing, writing, and searching files.

## Architecture

```text
                         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
```

## Features

* **MCP-based tool architecture**
* Local FastMCP server using HTTP transport
* LangChain agent with tool calling
* Local LLM inference through Ollama
* PDF file reading
* DOCX file reading and writing
* File listing with extension filtering
* Searching inside PDF and DOCX files
* Conversation state using LangGraph checkpointing
* Automatic tool selection by the LLM


## Tech Stack

* Python
* LangChain
* LangGraph
* Ollama
* Qwen3 1.7B
* FastMCP
* Model Context Protocol (MCP)
* `langchain-mcp-adapters`
* PyPDF
* python-docx

## Project Structure

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

## Installation

### 1. Clone the repository

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

### 2. Install Python dependencies

```bash
pip install -r requirements.txt
```

### 3. Install Ollama

Install Ollama from the official website and make sure it is running locally.

Then pull the model:

```bash
ollama pull qwen3:1.7b
```

You can verify that the model is available with:

```bash
ollama list
```

## Running the Project

The project uses two processes because the MCP server communicates with the client over HTTP.

### Terminal 1 — Start the MCP server

Run this command from the project root:

```bash
python fs_mcp.py
```

The server should be available at:

```text
http://127.0.0.1:8000/mcp
```

### Terminal 2 — Start the agent

Open another terminal in the project root:

```bash
python main.py
```

You can then enter requests such as:

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

or:

```text
List all PDF files in the tests folder.
```

or:

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

## Example Agent Flow

For a request such as:

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

the agent performs the following:

```text
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
```



## Requirements

Python 3.11+ is recommended.

Ollama must be installed and running locally.

The Qwen model must be available:

```bash
ollama pull qwen3:1.7b
```
You can also use a model through an inference provider.

## Dependencies

The project's direct dependencies are:

```text
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
```

## Future Improvements

* Add support for more file formats
* Add file deletion and directory creation tools
* Add stronger path validation and sandboxing
* Add authentication for remote MCP servers
* Add streaming responses
* Add richer document parsing
* Add persistent conversation storage
* Add additional MCP servers for databases, GitHub, or web search
* Improve tool-selection reliability with larger local models

## Learning Goals

This project demonstrates the interaction between:

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

It is intended as a practical example of building an **agentic application with Model Context Protocol (MCP)** and locally hosted LLMs.