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. Системний промпт і guardrails: prompts/PROMPT_BOOK.md. Сценарій відео-демонстрації: docs/DEMO_SCRIPT.md.

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

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

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):

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()).

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