Домашній файловий агент (Home File Agent)

Навчальний курсовий MCP-проєкт: агент, який працює з файлами в одній заданій локальній папці — шукає за змістом (RAG), читає, звітує про власний стан. Клієнт — Claude Desktop (MCP-конектор) або власний agent_loop.py.

Архітектура одним абзацом

Claude (LLM) ↔ MCP-сервер (server.py, FastMCP) ↔ локальна папка (файли) + Voyage AI (ембединги) + Chroma (векторна БД, локальна). Усі операції з файлами проходять через sandbox-перевірку кореневої папки. Повна архітектурна схема — окремо, у Draw.io (додається до захисту).

Джерела даних

Джерело	Роль	Де живе
Локальна папка (AGENT_ROOT_DIR)	Основні дані користувача (txt, md, pdf, docx, xml, xlsx, xls)	На диску користувача
Voyage AI (voyage-4-lite)	Ембединги для семантичного пошуку	Зовнішній API
Chroma	Векторна БД для RAG-пошуку	Локально, .chroma_index/

Встановлення

cd C:\Home_agen_LLM
python -m venv venv
.\venv\Scripts\Activate.ps1
pip install -r requirements.txt

Налаштування оточення

Створи .env:

ANTHROPIC_API_KEY=<потрібен лише для agent_loop.py, не для Claude Desktop> VOYAGE_API_KEY=<з voyageai.com> AGENT_ROOT_DIR=C:\Home_agen_LLM\test_data

Локальний запуск через Claude Desktop (основний спосіб)

1. Settings → Developer → Edit Config у Claude Desktop.
2. Додай у claude_desktop_config.json:

   {
     "mcpServers": {
       "home-file-agent": {
         "command": "C:\\Home_agen_LLM\\venv\\Scripts\\python.exe",
         "args": ["C:\\Home_agen_LLM\\server.py"],
         "env": {
           "AGENT_ROOT_DIR": "C:\\Home_agen_LLM\\test_data",
           "VOYAGE_API_KEY": "<ключ>"
         }
       }
     }
   }

3. Повний вихід із Claude Desktop і повторний запуск.
4. У чаті: "Проіндексуй мою папку", потім будь-яке питання по вмісту.

Локальний запуск через власний цикл (agent_loop.py, ДЗ1-доказ)

python agent_loop.py

Потребує ANTHROPIC_API_KEY в .env.

Доступні tools

• list_folder(path="") — список файлів/підпапок
• read_file(path) — вміст файлу (txt, md, pdf, docx, xml, xlsx, xls)
• reindex() — перебудова RAG-індексу (запускати після зміни файлів)
• search_files(query, top_k=5) — семантичний пошук
• status() — стан індексу (для моніторингу)

Тести

pip install pytest pytest-asyncio ruff
pytest tests/ -v
ruff check .

Docker / хмарний варіант

docker build -t home-file-agent .
docker run -i -p 8080:8080 `
  -e VOYAGE_API_KEY=<ключ> `
  -e AGENT_ROOT_DIR=/data `
  -v C:\Home_agen_LLM\test_data:/data `
  home-file-agent

Моніторинг

• agent.log — структуровані логи (без вмісту файлів)
• python check_health.py — перевірка свіжості індексу й аномалій у логах (exit code 0/1)
• tool status() — те саме, але прямо з чату

Безпека

Детально — у PROMPT_BOOK.md. Коротко: read-only, sandbox на кореневу папку, allowlist розширень, ліміт розміру файлу, rate limiting, приховані файли недоступні, логи без вмісту.