synology-chat-hermes-mcp

English · 繁體中文

制約付き FastMCP HTTP サーバーです。固定された Synology NAS の SMB 共有を AI エージェントに読み書き可能なファイルツールとして公開します。パスの厳格な隔離、サイズ制限、アクティブコンテンツの拒否が組み込まれています。

当初はファミリー向け Hermes デプロイメント（制御エージェント → MCP → SMB3 → NAS）のファイルチャネルとして構築されました。任意の MCP クライアント（Hermes、Claude など）で動作します。

存在理由

ファイルアクセスを持つ AI エージェントは、そのアクセス範囲が制限されている場合にのみ安全です。このサーバーは以下の機能を備えています：

• すべてのパスを隔離 — 1つの固定共有（NAS_SHARE）に制限します。パストラバーサル（..、絶対パス、シンボリックリンク/リパースポイントのエスケープ）は、SMB 呼び出しの前に拒否されます。

• 公開 WAN サーバーを拒否 — NAS_SERVER はプライベート、リンクローカル、または Tailscale（100.64.0.0/10）の固定 IP アドレスである必要があります。DNS 名やパブリック IP は拒否されます。

• 認証情報を保存しない — SMB パスワードは起動時に Docker シークレットファイル（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 が返されます。一度に1階層ずつ作成してください。

クイックスタート

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 パスワードはシステム内で唯一の機密情報であり、Docker シークレットファイルにのみ存在します。ハードコードは一切なく、非機密のチューニング値を除き .env に平文で保存されることもありません（.env は git 管理対象外です）。

• 本番環境ではプライベートインターフェースにバインドしてください。:8000 を公開しないでください。

• 共有名と SMB ユーザーは設定値（NAS_SHARE、NAS_USERNAME）です。デプロイメントごとに設定してください。コード内で特定の値を想定することはありません。

ライセンス

MIT