🚀 MCP-based Intelligent CS Wiki

본 프로젝트는 인간과 AI 에이전트가 공동으로 운영하며, 스스로 지식을 확장하고 구조적 결함을 검수하는 지능형 컴퓨터 과학(CS) 지식 베이스입니다.

---

⏱️ 30분 퀵스타트 가이드

처음 방문한 관리자가 30분 안에 자신의 자료 1건으로 첫 위키 페이지를 만들고 화면에서 확인할 수 있는 가이드입니다.

1. 설치 (환경 및 의존성)

• 실행 환경: Python 3.8 이상 버전이 설치되어 있어야 합니다.
• 의존성: 본 프로젝트는 별도의 외부 패키지 설치(pip install)가 필요하지 않으며, Python 표준 라이브러리(os, sys, re, subprocess 등)만으로 독립적으로 동작하도록 설계되었습니다.
• 준비: 프로젝트 루트 디렉토리에서 터미널을 열어 준비합니다.

2. 자료 투입

1. 프로젝트 내 data/raw/ 디렉토리로 이동합니다.
2. 위키로 변환하고자 하는 본인만의 원문 자료를 텍스트 파일(예: my_first_cs_note.txt)로 생성하여 저장합니다.
   • Tip: 운영체제, 컴퓨터 네트워크, 컴퓨터 보안과 관련된 핵심 개념을 넣으면 에이전트가 더 풍부한 상호 참조 링크를 생성합니다.

3. 통합 요청 방법 (위키 생성)

자료 투입이 완료되면, AI 에이전트 파이프라인 엔진을 가동하여 위키 생성을 요청합니다. 루트 디렉토리 터미널에서 다음 명령어를 실행합니다.

python src/main.py

• 진행 과정: 메인 파이프라인이 실행되면 Gemini 에이전트가 data/raw/의 텍스트를 읽어 스키마에 맞춘 마크다운으로 변환합니다. 이때 시스템은 순수 마크다운 데이터만 추출하여 docs/wiki/ 디렉토리에 자동으로 기록합니다.

4. 검증 방법 및 결과 확인

1. 파일 확인: 파이프라인 실행 완료 후, docs/wiki/ 폴더에 my_first_cs_note.md 파일이 생성되었는지 확인합니다.
2. 화면 렌더링 확인 (선택): Streamlit 대시보드(구현된 경우) 또는 로컬 마크다운 뷰어(VS Code 프리뷰 등)를 통해 문서가 정상적으로 렌더링되는지 확인합니다.
3. 거버넌스 테스트:
   • 생성된 마크다운 파일 하단의 <!-- [Human Protected: Start] --> 와 End 태그 사이에 "이것은 중요한 인간의 메모입니다."라고 직접 적고 저장합니다.
   • 터미널에서 python src/main.py를 다시 실행해 봅니다.
   • 실행 후 마크다운 파일을 다시 열었을 때, 해당 메모가 덮어씌워지지 않고 그대로 보존되어 있다면 검증 성공입니다.

---

🛠️ MCP Tool 목록과 동작 과정

본 시스템의 핵심인 에이전트가 로컬 환경 및 외부와 상호작용하기 위해 사용하는 MCP(Model Context Protocol) 기반 내장 도구들의 상세 정보입니다. (src/tools/wiki_tools.py에 구현)

1. read_wiki(page_name)

• 기능: 특정 위키 문서 읽기.
• 동작 과정: 에이전트가 현재 위키 지식 베이스(docs/wiki/)에 있는 마크다운 파일을 읽어야 할 때 호출합니다. 파일이 존재하지 않으면 에러 처리를 통해 에이전트에게 알립니다.

2. write_wiki(page_name, content)

• 기능: 데이터 거버넌스가 적용된 위키 문서 기록.
• 동작 과정:
  1. 에이전트가 작성한 새로운 마크다운 콘텐츠를 인자로 받습니다.
  2. 기존 파일이 존재할 경우 정규표현식(Regex)을 사용하여 기존 문서의 <!-- [Human Protected: Start] --> 태그 사이의 '인간 작성 데이터'를 추출합니다.
  3. 에이전트가 새로 전달한 콘텐츠의 해당 위치를 추출한 '인간 작성 데이터'로 강제 치환합니다.
  4. 최종 병합된 안전한 콘텐츠를 마크다운 파일로 저장합니다.

3. search_cve(keyword)

• 기능: 실시간 보안 취약점 메타데이터 조회 (시뮬레이터).
• 동작 과정: OS나 네트워크 문서를 작성하던 에이전트가 보안 컨텍스트 확장이 필요할 때 키워드(예: 'Buffer Overflow')와 함께 호출합니다. 툴은 가상의 CVE 데이터베이스를 조회하여 취약점 ID, 심각도(Severity), 요약 정보를 JSON/Dict 형태로 반환하여 에이전트가 문서에 결합할 수 있게 합니다.

---

🏗️ 시스템 아키텍처 및 운영 지침

• 에이전트 거버넌스 (config/RULES.md): 에이전트는 'CS 지식 자율 증식 에이전트'로서 활동하며, 스키마 준수(docs/scheme/page_template.md) 및 인간 보호 구역 절대 보존 원칙을 따릅니다.
• Pre-Write Hook: 문서가 저장되기 직전, 내부 링크 정합성과 마크다운 순수성을 강제 검증하는 시스템 훅입니다.
• Security Audit Subagent: 보안, 네트워크 관련 문서 작업 시 활성화되어 search_cve 도구를 적극 활용하는 하위 에이전트 스킬입니다.

---

Author: CS Wiki Maintenance Team Last Updated: 2026-06-16