AWS DevOps Study KB

AWS DevOps Engineer Professional 시험 준비를 위한 자체 호스팅 메모 지식 베이스입니다. 메모를 직접 작성하는 사람은 당신이 아니라 AI 에이전트입니다. Claude, OpenWebUI 또는 다른 에이전트에게 학습 질문(“gp3와 io2의 기본 성능 차이는 무엇이고, 각각 언제 선택해야 하나요?”)을 하면, 에이전트는 답변의 부수 효과로 잘 구조화되고 태그가 달린 메모를 여기에 저장합니다. AWS Knowledge MCP server에도 연결되어 있다면 그 메모는 공식 AWS 문서에 근거하게 됩니다. 다음 주에 다시 질문하면 에이전트는 답을 처음부터 다시 도출하는 대신 저장된 메모를 찾아냅니다.

폴더도, 수동 정리도 없습니다. 모든 메모는 계층 구조 없이 태그만으로 정리되며 전체 텍스트 검색이 가능합니다. 웹 UI는 설계상 읽기 전용입니다. 모든 쓰기는 에이전트가 담당합니다.

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 서비스가 동일한 메모 저장소를 세 가지 방식으로 노출하므로, AI 클라이언트가 지원하는 방식이 무엇이든 작동합니다.

• 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 (/) — 간단한 쿠키 세션 로그인으로 접근이 제한되는, 읽기 전용 탐색/검색/태그 필터 뷰입니다. 생성/편집 폼은 아예 존재하지 않습니다. 이는 실수가 아니라 의도된 설계입니다.

세 가지 모두 하나의 SQLite 기반 서비스 위에 있는 얇은 어댑터입니다(검색은 FTS5 전체 텍스트 + 태그 필터링). 따라서 MCP 클라이언트가 보는 것과 REST 클라이언트가 보는 것 사이에 불일치가 생길 수 없습니다. 아키텍처에 대한 자세한 내용은 CLAUDE.md를 참조하세요.

Related MCP server: OmniHub

빠른 시작

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을 사용하며, 열어야 할 인바운드 포트가 없습니다.

AI 에이전트 연결하기

모든 소비자는 .env의 Bearer 토큰(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 또는 mcpServers JSON 블록으로 구성되는 모든 클라이언트:

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

OpenWebUI: 사용 중인 OpenWebUI 버전에 네이티브 MCP 지원이 있다면, 동일한 URL + 헤더를 사용해 MCP 도구 서버(설정 → 도구)로 추가하세요.

연결되면 서버의 MCP instructions 필드(이를 따르는 클라이언트는 자동으로 읽음)가 이미 모델이 답변하기 전에 검색하고, 별도 요청 없이도 메모를 저장하도록 유도합니다. 클라이언트가 이 필드를 자동으로 처리하는 방식에 의존하지 않고 시스템 프롬프트를 통해 이 동작을 명시적이고 확실하게 만들고 싶다면 docs/agent-persona.md를 참조하세요.

OpenAPI/REST 도구 호출 클라이언트

MCP를 사용하는 대신 OpenAPI 스펙을 가져와 사용하는 모든 클라이언트(사용자 지정 GPT Actions, LibreChat, 사용자 지정 봇)의 경우:

• 스펙 URL: https://<your-host>/openapi.json (Bearer 토큰으로 보호됨 — 헤더를 포함해 가져오세요)

• 라이브 페치 대신 파일이 필요한 클라이언트를 위해 openapi/generated.json에 정적 복사본이 커밋되어 있습니다(스키마 변경 후 npm run generate:openapi로 재생성).

• 모든 호출에는 동일한 Authorization: Bearer <API_BEARER_TOKEN> 헤더가 필요합니다.

태그 규칙

폴더가 없으므로 태그가 유일한 정리 구조입니다. 에이전트는 태그를 일관되게 사용해야 합니다. AWS DevOps Pro 시험의 6개 도메인에는 exam:<domain>, 여기에 자유 형식 주제 태그(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