# DevOps Copilot Agent — курсовий проєкт (MCP-агент)

Q&A-агент для DevOps-інфраструктури: відповідає на питання про хости, Terraform-політики та логи, спираючись на джерела контексту цього репозиторію. Курсовий проєкт з поступовою побудовою через 4 домашні завдання.

## Roadmap

| Етап | Зміст | Статус |
|---|---|---|
| 1  | Цикл викликів агента, prompting-стратегії, системні обмеження | ✅ виконано |
| 2  | Інтеграція контексту: RAG над `CLAUDE.md`/`vm-deploy/CLAUDE.md`, детермінований `lookup_host` над `HOSTS.md` | ✅ виконано |
| 3  | Ядро: MCP-сервер бізнес-сценарію (`mcp_server/` — `search_infra_docs`, `lookup_host`, `query_logs`) | ✅ виконано |
| 4  | Production: розгортання в Docker, спільний моніторинг, CI/CD | 🟡 docker-compose та моніторинг готові (`infra/local/`), CI/CD-конвеєр — заплановано |

`MCP_Project` — головний і єдиний проєкт курсової роботи: власний MCP-сервер (`devops-copilot-mcp`) та ELK MCP-сервер (`elk-logs`, використаний з попереднього завдання, під час збірки клонується з upstream-репозиторію `elastic/mcp-server-elasticsearch`) розгортаються одним docker-compose зі спільним моніторингом.

Детальніше про рішення та архітектуру: [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md). Системний промпт і guardrails: [`prompts/PROMPT_BOOK.md`](prompts/PROMPT_BOOK.md). Сценарій відео-демонстрації: [`docs/DEMO_SCRIPT.md`](docs/DEMO_SCRIPT.md).

## Локальний запуск

### 1. MCP-інфраструктура (Docker) — розгорнути першою

```bash
cd MCP_Project/infra/local
cp .env.example .env   # ES_*, MCP_API_KEY, AGENT_API_KEY, GRAFANA_* — заповнити реальними значеннями
docker compose up -d --build
```

Розгортає: `devops-copilot-mcp` (власний MCP-сервер, `mcp_server/`, чотири інструменти), `mcp-elasticsearch` (`elk-logs`, використаний з попереднього завдання, збирається з upstream-репозиторію `elastic/mcp-server-elasticsearch`), шлюз автентифікації nginx на порту `:8080`, а також спільний моніторинг (Prometheus на `:9090`, Grafana на `/grafana/`, Loki/Promtail, cAdvisor).

Підключення зовнішнім MCP-клієнтом (наприклад, Claude Code):
```bash
claude mcp add --transport http devops-copilot http://localhost:8080/mcp --header "Authorization: Bearer $AGENT_API_KEY"
```

### 2. Агент (ДЗ1, інтерактивний CLI) — після кроку 1

`agent/cli.py` — MCP-клієнт до щойно розгорнутого `devops-copilot-mcp` (без локального коду інструментів — їхні схеми отримуються динамічно через `mcp_session.list_tools()`).

```bash
cd MCP_Project
python3 -m venv .venv && source .venv/bin/activate
pip install -e .
cp .env.example .env
# вписати власний ANTHROPIC_API_KEY і той самий AGENT_API_KEY, що згенерований в infra/local/.env
python -m agent.cli
```

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

- `sample-data/CLAUDE.md` — Terraform-політика режиму "лише читання", карта репозиторіїв → RAG (`search_infra_docs`)
- `sample-data/vm-deploy/CLAUDE.md` — SSH-політика режиму "лише читання" → RAG (`search_infra_docs`)
- `sample-data/vm-deploy/HOSTS.md` — інвентар хостів → детермінований парсинг (`lookup_host`), без застосування RAG (точний пошук надійніший за семантичний для табличних даних — див. Prompt Book)
- `elk-logs` MCP (`infra/local`, використаний з попереднього завдання, клонується з upstream-репозиторію під час збірки) — доступ до логів Elasticsearch через інструменти `list_log_indices`/`query_logs` (Query DSL, а не ES|QL — сумісний із будь-якою версією Elasticsearch, деталі в Prompt Book)

`sample-data/` — анонімізований приклад (вигадана компанія, IP-адреси, майданчики) у тому самому форматі, що й реальні внутрішні документи; вбудований безпосередньо в Docker-образ, тож проєкт є демонстровним і відтворюваним без доступу до чиєїсь реальної інфраструктури. Щоб підключити реальні документи замість sample-даних — див. коментарі в `infra/local/.env.example` та `infra/local/docker-compose.yml` (змінні середовища `ROOT_CLAUDE_MD`/`VM_DEPLOY_CLAUDE_MD`/`HOSTS_MD` та монтування тому). RAG використовує локальні embeddings (`sentence-transformers/all-MiniLM-L6-v2`), вбудовані в образ на етапі збірки — зовнішній API-ключ для цього не потрібен. `EmbeddingProvider`/`DocumentSource` — абстрактні інтерфейси (`mcp_server/rag/`), точка розширення для майбутніх джерел (Kubernetes API, бази даних) або інших постачальників embeddings.

## Безпека

Агент побудований у режимі "лише читання": не виконує і не рекомендує виконувати команди, що змінюють стан інфраструктури (`terraform apply`, `ansible-playbook` тощо). Деталі — у Prompt Book.

## Посилання (заповнюються перед здачею)

- Відео-демонстрація: _TBD_
- Архітектурна схема (Miro/Draw.io): _TBD_
- Репозиторій: _TBD_