AWS DevOps Study KB

Самостоятельно размещаемая база знаний памяток для подготовки к экзамену AWS DevOps Engineer Professional — заметки пишете не вы, а ваш ИИ-агент. Задайте Claude, OpenWebUI или любому другому агенту учебный вопрос («в чём базовая разница в производительности между gp3 и io2 и когда что выбрать?»), и он сохранит здесь хорошо структурированную памятку с тегами как побочный эффект ответа — с опорой на официальную документацию AWS, если он также подключён к AWS Knowledge MCP server. Спросите снова на следующей неделе — и агент найдёт памятку вместо того, чтобы заново выводить ответ.

Никаких папок, никакой ручной организации — каждая памятка плоская, с тегами и полнотекстовым поиском. Веб-интерфейс по замыслу только для чтения: все записи выполняют агенты.

you: "explain EBS volume types, baseline performance, and when to pick each"
agent: [searches this KB — nothing found] [answers, grounded in AWS docs] [saves a memo,
        tagged ebs, storage, exam:resilient-cloud-solutions]

 ...two weeks later...

you: "remind me about EBS gp3 vs io2"
agent: [searches this KB — finds the memo] "Yep, saved this one already — gp3 baseline is
        3,000 IOPS / 125 MiB/s regardless of size..."

Как это работает

Один сервис на Node.js/TypeScript предоставляет одно и то же хранилище памяток тремя способами, поэтому он совместим с любым вашим ИИ-клиентом:

• MCP (/mcp, streamable-HTTP) — для Claude Code, Claude Desktop, OpenWebUI или любого другого MCP-нативного клиента. Инструменты: create_memo, search_memos, get_memo, list_tags, update_memo, delete_memo.

• REST + OpenAPI (/api/v1/*, спецификация по адресу /openapi.json) — для агентных фреймворков и ботов, которые работают только с вызовами инструментов OpenAPI/REST (пользовательские GPT Actions, LibreChat, собственный Telegram-бот и т. д.).

• Web UI (/) — представление только для чтения с просмотром, поиском и фильтром по тегам для вас, защищённое простым входом через cookie-сессию. Форм создания/редактирования нет вообще — это не упущение, в этом суть.

Все три — тонкие адаптеры поверх одного сервиса на базе SQLite (поиск — полнотекстовый FTS5 + фильтрация по тегам), поэтому между тем, что видит MCP-клиент, и тем, что видит REST-клиент, не может возникнуть расхождений — подробнее об архитектуре см. в CLAUDE.md.

Related MCP server: XMemo

Быстрый старт

git clone <this-repo-url>
cd aws-devops-study-kb
cp .env.example .env        # fill in API_BEARER_TOKEN and SESSION_COOKIE_SECRET (see below)
npm install
npm run dev                 # http://localhost:8000

Сгенерируйте настоящие секреты, а не оставляйте заполнители из .env.example:

openssl rand -hex 32   # → API_BEARER_TOKEN
openssl rand -hex 32   # → SESSION_COOKIE_SECRET

Для постоянного развёртывания, доступного из интернета (чтобы к нему мог обратиться и облачный агент, и Telegram-бот), см. docs/deployment.md — Docker Compose + Cloudflare Tunnel, без необходимости открывать входящие порты.

Подключение ИИ-агента

Каждому потребителю нужен bearer-токен из .env (API_BEARER_TOKEN) в виде Authorization: Bearer <token>. Выберите путь, который подходит вашему клиенту.

MCP-клиенты (Claude Code, Claude Desktop, OpenWebUI, …)

Claude Code, при работающем развёртывании:

claude mcp add --transport http aws-devops-study-kb https://<your-host>/mcp \
  --header "Authorization: Bearer <API_BEARER_TOKEN>"

Claude Desktop или любой клиент, настраиваемый через JSON-блок mcpServers:

{
  "mcpServers": {
    "aws-devops-study-kb": {
      "type": "http",
      "url": "https://<your-host>/mcp",
      "headers": { "Authorization": "Bearer <API_BEARER_TOKEN>" }
    }
  }
}

OpenWebUI: добавьте его как сервер MCP-инструментов (Настройки → Инструменты) с тем же URL и заголовком, если ваша версия OpenWebUI поддерживает MCP нативно.

После подключения поле MCP instructions сервера (автоматически читается клиентами, которые его поддерживают) уже подталкивает модель искать перед ответом и сохранять памятки без дополнительной команды — см. docs/agent-persona.md, если вы хотите сделать это поведение явным и надёжным через системный промпт, а не полагаться на то, что клиент его подхватит.

Клиенты с вызовом инструментов через OpenAPI/REST

Для всего, что импортирует спецификацию OpenAPI, а не говорит на MCP (пользовательские GPT Actions, LibreChat, собственный бот):

• URL спецификации: https://<your-host>/openapi.json (защищён bearer-токеном — получайте его с заголовком)

• Статическая копия сохранена в openapi/generated.json, если вашему клиенту нужен файл, а не получение по сети (перегенерируйте с помощью npm run generate:openapi после любого изменения схемы).

• Каждый вызов требует тот же заголовок Authorization: Bearer <API_BEARER_TOKEN>.

Соглашение о тегах

Папок нет — теги являются единственной организующей структурой, поэтому агенты должны использовать их согласованно. exam:<domain> для 6 доменов экзамена AWS DevOps Pro, плюс свободные теги тем (ebs, s3, codepipeline, …). Полное соглашение и то, где оно применяется/документируется для агентов, — в docs/tag-conventions.md.

Разработка

npm test              # vitest — memoService, REST API, and MCP tool round-trips
npm run typecheck      # tsc --noEmit
npm run build           # compiles to dist/ (used by the Docker image)

Полное описание архитектуры (почему SQLite+FTS5, зачем один общий сервисный слой, модель аутентификации, известные подводные камни) — в CLAUDE.md, если вы расширяете этот проект.

Лицензия

MIT