synology-chat-hermes-mcp

English · 繁體中文

Un servidor HTTP FastMCP restringido que expone un recurso compartido SMB fijo de un NAS Synology a agentes de IA como herramientas de archivos de lectura/escritura, con un estricto confinamiento de rutas, límites de tamaño y rechazo de contenido activo incorporado.

Originalmente construido como el canal de archivos para un despliegue familiar de Hermes (agente de control → MCP → SMB3 → NAS). Funciona con cualquier cliente MCP (Hermes, Claude, etc.).

Por qué existe esto

Los agentes de IA con acceso a archivos solo son seguros si el acceso está acotado. Este servidor:

• Confinamiento de cada ruta a un único recurso compartido fijo (NAS_SHARE). El path traversal (.., rutas absolutas, escape mediante enlaces simbólicos/puntos de reanálisis) se rechaza antes de cualquier llamada SMB.

• Rechaza servidores WAN públicos — NAS_SERVER debe ser una IP literal privada, de enlace local o de Tailscale (100.64.0.0/10). Los nombres DNS y las IPs públicas son rechazados.

• Nunca almacena credenciales — la contraseña SMB se lee de un archivo secreto de Docker al iniciar (NAS_PASSWORD_FILE), nunca de variables de entorno ni del código.

• Bloquea contenido activo — los generadores de DOCX/XLSX/PDF producen solo documentos sanitizados; las cargas binarias se analizan en busca de macros, relaciones externas y scripts; se rechazan las discrepancias entre extensión y tipo de medio.

• Acota todo — el tamaño de archivo, el tamaño binario, los caracteres del documento, las celdas de la hoja de cálculo, los píxeles de la imagen y los resultados de búsqueda tienen límites estrictos.

• Audita las operaciones — cada mutación se añade a un registro de auditoría en formato JSONL.

Related MCP server: MCP File System Server

Arquitectura

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

Herramientas

Limitación conocida: create_directory valida el padre antes de makedirs, por lo que una ruta de varios niveles cuyo primer segmento no exista devuelve not_found incluso con parents=True. Cree un nivel a la vez.

Inicio rápido

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

Verificación de estado:

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":{}}}'

Configuración de MCP para Hermes

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

Ejecución de pruebas

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

Referencia de variables de entorno

Notas de seguridad

• La contraseña SMB es el único secreto del sistema y reside solo en el archivo secreto de Docker. Nada está codificado, nada se almacena en .env en texto plano más allá de valores de ajuste no secretos (y .env está en gitignore).

• En producción, enlace a una interfaz privada; no exponga :8000 públicamente.

• El nombre del recurso compartido y el usuario SMB son configuración (NAS_SHARE, NAS_USERNAME) — establézcalos por despliegue; nada en el código asume un valor particular.

Licencia

MIT