synology-chat-hermes-mcp

영어 · 繁體中文

제한된 FastMCP HTTP 서버로, 고정된 Synology NAS SMB 공유를 AI 에이전트에 읽기/쓰기 파일 도구로 노출합니다. 엄격한 경로 감옥, 크기 제한, 활성 콘텐츠 거부가 내장되어 있습니다.

원래 가족 Hermes 배포(제어 에이전트 → MCP → SMB3 → NAS)의 파일 채널로 구축되었습니다. 모든 MCP 클라이언트(Hermes, Claude 등)와 함께 작동합니다.

존재 이유

파일 접근 권한이 있는 AI 에이전트는 접근이 제한될 때만 안전합니다. 이 서버는:

• 모든 경로를 하나의 고정된 공유(NAS_SHARE)로 감금합니다. 경로 탐색(.., 절대 경로, 심볼릭 링크/재분석 지점 탈출)은 SMB 호출 전에 거부됩니다.

• 공용 WAN 서버를 거부합니다 — NAS_SERVER는 사설, 링크-로컬 또는 Tailscale(100.64.0.0/10) 리터럴 IP여야 합니다. DNS 이름과 공용 IP는 거부됩니다.

• 자격 증명을 저장하지 않습니다 — SMB 비밀번호는 시작 시 도커 시크릿 파일(NAS_PASSWORD_FILE)에서 읽으며, 환경 변수나 코드에서 절대 읽지 않습니다.

• 활성 콘텐츠를 차단합니다 — DOCX/XLSX/PDF 작성기는 정리된 문서만 생성합니다. 바이너리 업로드는 매크로, 외부 관계, 스크립트를 검사합니다. 확장자/미디어 유형 불일치는 거부됩니다.

• 모든 것을 제한합니다 — 파일 크기, 바이너리 크기, 문서 문자 수, 스프레드시트 셀, 이미지 픽셀, 검색 결과 모두에 하드 제한이 있습니다.

• 작업을 감사합니다 — 모든 변경 사항은 JSONL 감사 로그에 추가됩니다.

Related MCP server: MCP File System Server

아키텍처

Hermes (or any MCP client)
  → HTTP :8000/mcp (FastMCP, streamable HTTP)
    → NasService (validation, limits, audit)
      → SMBBackend (smbprotocol, SMB3, encryption+signing required)
        → Synology NAS share

도구

알려진 제한 사항: create_directory는 makedirs 전에 부모를 검증하므로, 첫 번째 세그먼트가 존재하지 않는 다중 레벨 경로는 parents=True에서도 not_found를 반환합니다. 한 번에 한 레벨씩 생성하세요.

빠른 시작

cp .env.example .env   # set NAS_SERVER (Tailscale/private IP), NAS_USERNAME
# provide the SMB password as a docker secret:
printf '%s' 'YOUR_SMB_PASSWORD' > ./synology_password
chmod 600 ./synology_password

docker build -t nas-mcp .
docker run -d --name nas-mcp \
  --env-file .env \
  -v "$PWD/synology_password:/run/secrets/synology_password:ro" \
  -v nas-mcp-audit:/var/log/nas-mcp \
  -p 8000:8000 \
  nas-mcp

상태 확인:

curl -X POST http://127.0.0.1:8000/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"health","arguments":{}}}'

Hermes MCP 구성

mcp_servers:
  nas-mcp:
    type: http
    url: http://nas-mcp:8000/mcp

테스트 실행

python -m nas_mcp.smoke   # exercises the full tool chain against the live share

환경 변수 참조

보안 참고 사항

• SMB 비밀번호는 시스템의 유일한 비밀이며 오직 도커 시크릿 파일에만 존재합니다. 하드코딩된 것은 없으며, 비밀이 아닌 조정 값 외에는 .env에 평문으로 저장되지 않습니다 (그리고 .env는 git에서 무시됩니다).

• 프로덕션에서는 사설 인터페이스에 바인딩하세요. :8000을 공개적으로 노출하지 마십시오.

• 공유 이름과 SMB 사용자는 구성(NAS_SHARE, NAS_USERNAME)입니다. 배포별로 설정하세요. 코드는 특정 값을 가정하지 않습니다.

라이선스

MIT