# MCP Hub 파일 공유(NAS) 연동 가이드

> **대상**: 사내 파일 서버 / NAS 담당자 · 툴킷 운영자
> **선행 조건**: 커넥터 설치 완료 ([Connector 설치 가이드](/guides/connector-installation)) + 툴킷 사용 가이드 숙지 ([Toolkit 사용 가이드](/guides/toolkit-usage))
> **본 문서는 파일 서버 측 작업 + 커넥터 마운트** 중심입니다

---

## 이 기능이 하는 일 · 하지 않는 일

AI 가 사내 파일 서버에서 **필요한 파일을 찾아내는 것**까지가 이 기능입니다.

| 하는 일                                        | 하지 않는 일                     |
| ---------------------------------------------- | -------------------------------- |
| 폴더 안에 무엇이 있는지 목록으로 보여주기      | 파일 내용을 도구 결과로 돌려주기 |
| 이름 · 확장자 · 수정일로 파일 찾기             | 파일을 만들거나 고치거나 지우기  |
| 찾은 파일마다 **참조(ref)** 하나씩 만들어 주기 | 참조 없이 아무 경로나 열기       |

**파일 내용은 도구 결과에 실리지 않습니다.** 도구는 목록과 참조만 돌려주고, 실제 파일은 WRKS AI 가 그 참조로 따로 내려받아 답변에 씁니다. 그래서 파일 100개를 찾아도 AI 대화에 들어가는 것은 목록뿐이고, 내용이 필요한 파일만 실제로 읽힙니다.

**읽기 전용입니다.** 파일을 바꾸거나 지우는 동작은 제품에 없습니다.

---

## 공통 보안 원칙

1. **읽기 전용으로 마운트** — 도커 `-v` 줄 끝에 `:ro`. 이 기능은 쓰기를 하지 않지만, 읽기 전용으로 붙여 두시면 설령 무슨 일이 생겨도 원본이 안전합니다
2. **마운트 계정의 OS 권한을 좁히세요** — **이것이 실제 경계입니다.** 커넥터가 볼 수 있는 범위가 곧 문제가 생겼을 때의 영향 범위입니다
3. **AI 에게 열 폴더를 따로 만드세요** — 부서 공유 전체를 통째로 붙이지 마시고, 전사에 공개해도 되는 자료만 모은 폴더를 만들어 그것만 마운트하시길 권합니다
4. **만드신 뒤 한 번 확인하셔야 열립니다** — 마운트에 실제로 무엇이 있는지 화면에서 보여 드리고, 확인하셔야 엔드포인트를 만들 수 있습니다 (아래 §3)

### 마운트 봉쇄를 어떻게 봐야 하나 — 솔직한 설명

AI 가 만든 경로는 파일 시스템에 그대로 전달되지 않습니다. 커넥터가 경로를 실제 위치로 굳힌 뒤 **마운트 폴더 안인지** 검사하고, 벗어나면 거절합니다. 절대 경로 · `..` · 심볼릭 링크로 밖을 가리키는 경우가 모두 여기서 막힙니다.

> ⚠️ **이걸로 다 막히지는 않습니다.** SMB 공유가 `wide links = yes` 로 열려 있으면 **서버가 심볼릭 링크를 미리 풀어서** 주기 때문에, 커넥터에는 평범한 파일로 보이고 위 검사가 통과합니다. Samba 기본값은 `no` 라 대개는 막히지만, 켜 두신 공유에서는 **서버 설정이 유일한 방어선**입니다.
>
> 공유 설정에서 `wide links` 를 끄시고(기본값), 그래도 켜 두셔야 한다면 위 2번 — 마운트 계정의 OS 권한을 좁히는 것으로 피해 범위를 줄여 주세요.

### 지금은 "전사 공용" 만 쓰실 수 있습니다

툴킷을 만드실 때 이 공유를 누구에게 열지 고르시는데, 지금 고르실 수 있는 것은 **전사 공용** 하나입니다.

- **전사 공용** — 이 공유의 모든 파일을 이 툴킷을 쓰는 누구나 봅니다. 사규 · 양식 · 제품 카탈로그처럼 전사에 공개해도 되는 자료에 쓰십니다
- **부서별** — 부서에 따라 볼 수 있는 폴더가 갈립니다. **아직 준비 중**이라 고르실 수 없습니다. 준비되면 안내드리겠습니다

부서별로 갈라야 하는 자료는 지금 붙이지 마시고, 전사에 공개해도 되는 폴더부터 시작하시길 권합니다.

---

## 1. 파일 서버를 커넥터 호스트에 마운트

### 1-1. 마운트하기

커넥터는 **호스트에 이미 마운트된 폴더**를 봅니다. NAS 를 직접 연결하지 않습니다.

```bash
# NFS 예시
sudo mkdir -p /mnt/nas/공유자료
sudo mount -t nfs 10.0.0.50:/volume1/공유자료 /mnt/nas/공유자료 -o ro

# SMB/CIFS 예시 — 자격 증명은 파일로 분리
sudo mount -t cifs //10.0.0.50/공유자료 /mnt/nas/공유자료 \
  -o ro,credentials=/etc/nas-credentials,uid=1000,iocharset=utf8
```

재부팅 후에도 유지되도록 `/etc/fstab` 에 넣어 두시길 권합니다.

```
10.0.0.50:/volume1/공유자료  /mnt/nas/공유자료  nfs  ro,_netdev  0  0
```

### 1-2. 마운트가 제대로 붙었는지 확인

```bash
# 마운트가 살아 있고 읽히는지
ls -la /mnt/nas/공유자료 | head

# 읽기 전용인지 — "read-only file system" 이 나와야 정상
touch /mnt/nas/공유자료/_test 2>&1
```

여기까지가 파일 서버 쪽 작업입니다. **커넥터에 이 폴더를 붙이는 명령은 다음 단계에서 화면이 만들어 드립니다.**

---

## 2. Studio 에서 툴킷 만들고 커넥터에 붙이기

1. **툴킷 → 새 툴킷 만들기**
2. **유형**에서 **파일 공유 (NAS)** 선택
3. **이름** 과 **Connector** 선택 — 공유 폴더를 붙이실 그 커넥터입니다
4. **이 공유를 누구에게 열까요?** 에서 **전사 공용** 선택
5. **공유 폴더 경로**에 §1-1 에서 마운트하신 경로를 넣습니다 (예: `/mnt/nas/공유자료`)
6. 화면이 **커넥터 실행 명령을 통째로** 만들어 드립니다. **[복사]** 해서 커넥터가 돌아가는 서버에서 실행해 주세요
7. 확인란 체크 후 **Toolkit 생성**

### 화면이 만들어 주는 명령은 이렇게 생겼습니다

```bash
docker rm -f mcp-connector-<커넥터이름>
docker run -d \
  --name mcp-connector-<커넥터이름> \
  ...
  -v /mnt/nas/공유자료:/var/nas:ro \
  -e MCP_NAS_MOUNT_DIR=/var/nas \
  ...
```

| 더해지는 줄                   | 하는 일                                                                 |
| ----------------------------- | ----------------------------------------------------------------------- |
| `-v <호스트경로>:/var/nas:ro` | 호스트에 마운트해 두신 폴더를 컨테이너 안으로. **`:ro` 를 빼지 마세요** |
| `MCP_NAS_MOUNT_DIR`           | 컨테이너 **안쪽** 경로. 위 `-v` 의 오른쪽과 같습니다                    |

**커넥터는 같은 이름·같은 저장소로 다시 뜹니다** — 인증서가 그대로 살아 있어 같은 커넥터로 다시 붙고, 그 커넥터에 걸린 다른 툴킷도 그대로 동작합니다.

> ⚠️ **커넥터 실행 명령을 직접 손보셨다면** 위 명령을 그대로 쓰지 마세요. 직접 더하신 `-v`·`-e` 줄이 빠집니다. 그 경우 쓰시던 명령에 위 두 줄만 더해 주세요 — 화면에도 **[커넥터 실행 명령을 직접 손보셨다면]** 을 펼치면 두 줄만 따로 있습니다.
>
> 두 줄을 더하실 때는 **이미지 이름(`ghcr.io/...`)보다 앞**에 넣어 주세요. 이미지 이름은 `docker run` 의 마지막 인자라, 그 뒤에 온 것은 옵션이 아니라 컨테이너에서 실행할 명령으로 읽힙니다.

### 실행 뒤 확인

```bash
# 컨테이너 안에서도 공유 폴더가 보이는지 (컨테이너 이름은 위 명령의 --name 값)
docker exec mcp-connector-<커넥터이름> ls -la /var/nas | head
```

> 공유 폴더 경로는 Studio 에 저장되지 않습니다. **어느 폴더를 보여줄지는 전적으로 이 마운트가 정합니다** — 그래서 툴킷 설정 화면에는 폴더를 바꾸는 칸이 없습니다. 바꾸시려면 경로를 고쳐 커넥터를 다시 띄우시면 됩니다.

---

## 3. 만드신 뒤 — 공유 폴더 확인 (필수)

툴킷을 만드셨다고 바로 AI 에게 보이지는 않습니다. **도구 탭**에 "아직 AI 에게는 이 도구가 보이지 않습니다" 안내와 함께 **[공유 폴더 확인하기]** 버튼이 나옵니다.

누르시면 마운트에 **실제로 있는 것 전부**를 보여 드립니다 — 최상위 폴더 목록, 파일 개수, 최근 수정된 파일 몇 건. 이걸 보시고 "우리가 열려던 그 공유가 맞다" 를 확인해 주시면 엔드포인트를 만드실 수 있고, 그때부터 AI 에게 도구가 보입니다.

> **왜 확인을 받나**: 전사 공용은 이 공유의 모든 파일을 누구나 보게 됩니다. 마운트를 한 칸 위로 잡으셨거나 예상 못 한 폴더가 섞여 있으면 그때 발견하시는 편이 낫습니다.
>
> **확인의 한계**: 확인하신 **그 시점의 내용**을 보신 것입니다. 확인 뒤에 기밀 파일이 그 폴더로 들어오면 그건 막지 못합니다. 공유 폴더에 무엇을 두실지는 계속 관리해 주셔야 합니다.

엔드포인트 발급은 툴킷 가이드와 동일합니다 ([Toolkit 사용 가이드](/guides/toolkit-usage)).

---

## 4. AI 가 쓰는 도구 3개

파일 공유 툴킷은 도구가 **자동으로** 만들어집니다. 문서를 올리실 필요가 없고, 켜고 끄거나 이름을 바꾸실 수도 없습니다.

| 도구           | 하는 일                                                             |
| -------------- | ------------------------------------------------------------------- |
| `list_files`   | 폴더 **하나**의 바로 아래 내용을 봅니다 (하위 폴더까지 뒤지지 않음) |
| `search_files` | 공유 전체에서 이름 · 확장자 · 수정일로 찾습니다 (하위 폴더까지)     |
| `fetch_file`   | 찾은 파일의 내용을 WRKS AI 가 내려받습니다                          |

> `fetch_file` 은 **WRKS AI 에서만 동작합니다.** 다른 MCP 클라이언트에 연결하시면 파일을 찾고 목록을 보는 것까지는 그대로 되지만, 파일 내용은 열리지 않습니다.

### 상한 — 결과가 잘릴 수 있습니다

| 상한                       | 값                      |
| -------------------------- | ----------------------- |
| 목록 한 번에 돌려주는 개수 | 기본 200개 · 최대 500개 |
| 검색 한 번에 찾는 개수     | 기본 100개              |
| 검색이 들어가는 폴더 깊이  | 8단계                   |
| 검색에 쓰는 시간           | 3초                     |

결과가 잘리면 **무엇에 걸려 잘렸는지**(개수 · 깊이 · 시간) 함께 알려 드립니다. 파일이 아주 많은 공유라면 폴더를 나눠 여러 툴킷으로 붙이시는 편이 찾기가 잘 됩니다.

---

## 5. 트러블슈팅

| 증상 / 표시                         | 원인 · 해결                                                                                            |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------ |
| `mount_not_configured`              | 커넥터에 `MCP_NAS_MOUNT_DIR` 이 없습니다 — §2 에서 화면이 만들어 준 명령으로 커넥터를 다시 띄워 주세요 |
| `mount_missing`                     | 지정하신 경로가 컨테이너 안에 없습니다 — `-v` 의 오른쪽과 `MCP_NAS_MOUNT_DIR` 이 같은지 확인           |
| `mount_not_directory`               | 폴더가 아니라 파일을 가리키고 있습니다                                                                 |
| `mount_unavailable`                 | 마운트가 끊겼습니다 — 호스트에서 `ls` 로 확인, NFS/SMB 재마운트                                        |
| `path_escape` · `path_absolute`     | 마운트 밖을 가리키는 요청이 거절됐습니다 — **정상 동작**입니다                                         |
| `path_not_found`                    | 그 경로에 파일·폴더가 없습니다. 한글 이름이면 아래 항목도 확인해 주세요                                |
| `path_ambiguous`                    | 이름이 **눈으로는 같은데 저장된 바이트가 다른** 파일이 한 폴더에 둘 이상 있습니다 (아래 참고)          |
| 도구 탭에 "AI 에게 보이지 않습니다" | §3 의 공유 폴더 확인을 아직 안 하셨거나, 엔드포인트가 없습니다 — 화면 안내가 어느 쪽인지 알려 줍니다   |
| 목록이 비어 있음                    | 마운트 계정에 그 폴더 읽기 권한이 없을 수 있습니다 — 호스트에서 커넥터 계정으로 `ls` 확인              |

### 한글 파일 이름이 안 찾아질 때

macOS 에서 만든 파일과 Windows 에서 만든 파일은 **같은 한글이라도 저장된 바이트가 다를 수 있습니다** (완성형 · 자모 분리). 커넥터는 양쪽을 같은 것으로 보고 찾아 주지만, **한 폴더 안에 두 방식이 섞여 같은 이름이 둘** 있으면 어느 쪽인지 정할 수 없어 거절합니다(`path_ambiguous`). 그 경우 파일 이름을 하나로 정리해 주세요.

---

## 6. 새 파일 공유 툴킷 만들기 전 체크리스트

- [ ] AI 에게 열 자료만 모은 **전용 공유 폴더**를 만들었다 (부서 공유 전체를 통째로 붙이지 않았다)
- [ ] 그 폴더에 **전사에 공개해도 되는 자료만** 있다 (부서별로 갈라야 하는 자료는 아직 붙이지 않는다)
- [ ] 커넥터 호스트에 **읽기 전용(`ro`)** 으로 마운트했다
- [ ] 만들기 화면이 준 명령을 커넥터 서버에서 실행했다 (직접 손보신 명령이 있으면 두 줄만 더했다)
- [ ] `docker exec ... ls /var/nas` 로 컨테이너 안에서 내용이 보인다
- [ ] 마운트 계정의 OS 권한이 그 폴더로 좁혀져 있다 — **이것이 실제 경계**
- [ ] SMB 공유의 `wide links` 가 꺼져 있다 (기본값)
- [ ] 재부팅 후에도 마운트가 유지되도록 `/etc/fstab` 에 넣었다
- [ ] 툴킷을 만든 뒤 **공유 폴더 확인**을 했고, 보인 목록이 예상과 같았다
- [ ] 공유 폴더에 무엇을 두는지 앞으로도 관리할 담당자가 정해져 있다