README.md•3.47 kB
# File System MCP Server (with LLM Agent Bridge)
이 프로젝트는 파일 시스템 작업을 LLM(예: Ollama) + MCP 도구 + Python 브리지(Agent)로 자동화하는 예제입니다.
---
## 아키텍처(최신 구조)
```
┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ 사용자 │ → │ bridge.py │ → │ mcp_server.py │ → │ backend_api.py│
│ (자연어 명령)│ │ (LLM+MCP Agent)│ │ (MCP 서버) │ │ (백엔드 API) │
└──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘
```
- **bridge.py**: Ollama(LLM)와 MCP 서버를 연결하는 Python 에이전트(Agent, 브리지)
- **mcp_server.py**: MCP 프로토콜을 구현한 파일 시스템 도구 서버
- **backend_api.py**: 실제 파일 시스템 작업을 수행하는 백엔드 API
---
## 주요 파일 설명
- `backend_api.py` : 파일/디렉토리 관리 REST API (포트 8001)
- `mcp_server.py` : MCP 프로토콜 서버, backend_api.py를 래핑 (포트 8000)
- `bridge.py` : Ollama(LLM)와 MCP 서버를 연결, 자연어 명령을 실제 작업으로 자동 실행
---
## 설치 및 실행 방법
### 1. 의존성 설치
```bash
pip install -r requirements.txt
```
### 2. 서비스 실행
#### 1) 백엔드 API 실행
```bash
python backend_api.py
```
#### 2) MCP 서버 실행
```bash
python mcp_server.py
```
#### 3) Ollama 서버 실행
```bash
ollama serve
```
#### 4) 브리지(Agent) 실행
```bash
python bridge.py
```
---
## 사용 예시 (자동화)
브리지 실행 후, 아래와 같이 자연어로 명령하면 실제 파일 시스템 작업이 자동 실행됩니다.
```
👤 사용자: test_source.txt를 test_dest.txt로 복사해줘
🤖 Ollama 처리 중...
📝 Ollama 응답:
{"tool": "copy_file", "inputs": {"source_path": "test_source.txt", "destination_path": "test_dest.txt"}}
🔧 MCP 도구 호출: copy_file
📋 매개변수: {'source_path': 'test_source.txt', 'destination_path': 'test_dest.txt'}
✅ 실행 결과:
{
"output": {
"source_path": "/Users/terzeron/workspace/mcp_test/test_source.txt",
"destination_path": "/Users/terzeron/workspace/mcp_test/test_dest.txt",
"bytes_copied": 94,
"message": "File copied successfully"
}
}
```
- 예시 명령:
- `현재 디렉토리 파일 목록 보여줘`
- `test_source.txt 파일 읽어줘`
- `새 파일 test.txt에 Hello World 써줘`
- `test_source.txt 파일 정보 보여줘`
- `새 폴더 backup 만들어줘`
- `test_source.txt를 test_copy.txt로 복사해줘`
- `test_copy.txt 파일 삭제해줘`
---
## Ollama 단독 사용법(참고)
Ollama만 사용할 경우, 실제 작업은 자동 실행되지 않고 curl 명령어 예시만 출력됩니다.
실제 자동화를 원한다면 반드시 bridge.py를 사용하세요.
---
## 기타
- 모든 서비스는 로컬에서 실행됩니다.
- bridge.py는 Ollama의 답변에서 도구 호출 JSON을 추출해 MCP 서버에 자동 요청합니다.
- MCP 서버와 백엔드 API는 FastAPI 기반입니다.
---
## 문의/확장
- 더 복잡한 에이전트, 대화형 챗봇, 여러 도구 조합 등 확장도 가능합니다.