Skip to main content
Glama
deenesjakoruzh
jibixn

MCP File System Agent

by jibixn
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

MCP 파일 시스템 에이전트

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: OmniMCP-Container

기능

  • MCP 기반 도구 아키텍처

  • HTTP 전송을 사용하는 로컬 FastMCP 서버

  • 도구 호출을 지원하는 LangChain 에이전트

  • Ollama를 통한 로컬 LLM 추론

  • 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 서버에 대한 인증 추가

  • 스트리밍 응답 추가

  • 더 풍부한 문서 파싱 추가

  • 영구 대화 저장소 추가

  • 데이터베이스, GitHub 또는 웹 검색을 위한 추가 MCP 서버 추가

  • 더 큰 로컬 모델로 도구 선택 신뢰성 개선

학습 목표

이 프로젝트는 다음 간의 상호 작용을 보여줍니다:

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

Model Context Protocol (MCP) 및 로컬 호스팅 LLM을 사용한 에이전트 애플리케이션 구축의 실용적인 예시로 제작되었습니다.

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivitySlowing
ResponsivenessNo issues

Resources

Related MCP Connectors

  • uldl
    sh.uldl

    Persistent file storage for AI agents via MCP and curl. Upload, download, and version files.

    File SystemsCloud StorageAgent Orchestration
    2
  • flockfsOAuth
    com.flockfs

    A real-time, multiplayer filesystem for agents and humans: shared files, live edits, history.

    File SystemsVersion ControlDeveloper Tools
    1
  • saagarpatel.dev PortfolioA
    io.github.saagpatel

    Agent-native MCP server over the public saagarpatel.dev corpus. Read-only, stateless.

    SearchDocumentation Access
    82
  • Fast.ioA
    io.fast.mcp

    Fastio gives your team and AI agents a workspace for each project, bringing source files, comments and new work together. Connect a compatible MCP client to find files, answer questions from project material, and save results where the team can review and use them. \ Sign in through Fastio and choose the workspaces the connection can reach. Read Only connections expose read tools; Read & Write connections also allow changes. \ • **Files and folders:** browse, read, upload, and organize files, with version history and trash. • **Search:** find files by keyword; search file content and meaning when Deep Indexing is enabled and files have been processed. • **Metadata:** read, set, and search metadata fields, including extracted fields where available. • **Shares:** create and manage shares for sending or collecting files. • **Comments and members:** read and add comments, and manage workspace membership within your permissions. • **Activity:** search workspace events to see what changed. \ Hosted by Fastio, with no server installation required. \ • **Claude and most MCP clients:** https://mcp.fast.io/mcp/tools • **ChatGPT:** https://mcp.fast.io/mcp/operations • **ChatGPT and Codex:** Fastio plugin • **Claude Code, Cursor and similar coding agents:** https://mcp.fast.io/mcp/code • **Setup and client-specific capabilities:** https://mcp.fast.io/docs \ Paid plans. Monthly plans include a trial of up to 30 days. A card is required, and billing begins when the trial ends or trial credits run out, whichever comes first. No free plan.

    Cloud StorageFile SystemsRAG Systems
    373

Related MCP Servers