AI 튜토리얼

FastAPI, SQLite, MCP로 로컬 파일 지식 베이스 구축 및 사용

FastAPI 지식 베이스 설치, SQLite 데이터베이스 초기화, 사용자 인증, 문서 업로드 및 정리, 지원 파일 미리보기, 읽기 전용 MCP 서비스를 통한 AI 에이전트 연결 방법을 알아보세요.

2026년 9월 23일약 14분 소요

FastAPI, SQLite, MCP로 로컬 파일 지식 베이스 구축 및 사용

개요

Knowledge Base Phase 1은 FastAPI, SQLite, 로컬 파일 시스템 저장소로 구축된 최소 기능 파일 지식 베이스입니다. 인증된 문서 관리, 중첩 폴더, 브라우저 로컬 미리보기, 메타데이터 및 태그, 관리자 도구, 감사 정보, 그리고 Model Context Protocol(MCP)을 통한 AI 에이전트의 읽기 전용 액세스를 지원합니다.

이 단계는 의도적으로 가볍게 구성되었습니다. Docker, PostgreSQL, MinIO, LibreOffice, ONLYOFFICE 또는 실행 중인 다른 데이터베이스 서비스가 필요하지 않습니다. PostgreSQL과 객체 저장소는 이후 마이그레이션을 위해 남겨 두었습니다.

프로젝트에서 제공하는 기능

관리자가 생성하는 사용자, 로그인 및 JWT 인증
중첩 폴더와 경로 표시 탐색을 지원하는 공개 지식 베이스
폴더 범위의 문서 목록, 단일 파일 업로드 및 일괄 업로드
PDF, 텍스트, Markdown, HTML, 이미지, PowerPoint, Word 및 Excel 파일 지원
문서 메타데이터, 태그, 소유자 및 업로더 정보
원본 파일 미리보기 및 다운로드
텍스트, Markdown, PDF, DOCX, XLSX, PPTX 및 이미지의 앱 내 읽기
레거시 DOC, XLS 및 PPT 파일의 가능한 범위 내 텍스트 추출
소유자 전용 문서 편집, 소프트 삭제, 복원, 폴더 이름 변경 및 빈 폴더 삭제
삭제된 문서를 위한 휴지통
재귀적 폴더 복사와 실제 저장소 복제를 포함한 범위 간 문서 및 폴더 복사
관리자 전용 사용자 관리, 감사 로그 및 MCP 호출 로그
읽기 전용 REST API, 생성된 OpenAPI 문서 및 MCP 통합

저장소 작동 방식

애플리케이션은 backend/data/ 아래에 런타임 파일을 생성합니다. SQLite 데이터베이스는 backend/data/knowledge_base.db로 저장되며, 업로드된 파일과 생성된 Markdown 파일은 backend/data/storage/ 아래에 저장됩니다.

로컬 저장소에는 경로 탐색 방지 기능이 포함되어 있습니다. 기존 Docker Compose 구성은 이후 PostgreSQL 및 객체 저장소 마이그레이션을 위한 것이며 이 단계에는 필요하지 않습니다.

백엔드 설치

1. 환경 파일 생성

PowerShell을 열고 저장소의 backend 디렉터리로 이동한 다음 루트 환경 템플릿을 backend/.env로 복사합니다.

cd backend
Copy-Item ..\.env.example .env

운영 설정은 .env.example, backend/app/core/config.py 및 scripts/ 아래의 PowerShell 제어 파일을 통해 정의됩니다.

2. Python 가상 환경 생성

python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt

이 명령은 backend 디렉터리에서 실행합니다. 가상 환경을 활성화하면 프로젝트 패키지가 전역 Python 설치와 분리됩니다.

3. SQLite 초기화

python -m app.db.init_db

이 명령은 필요한 SQLite 테이블을 초기화하거나 다시 생성합니다. 테이블을 다시 생성하면 기존 데이터에 영향을 줄 수 있으므로 문서 저장을 시작한 후에는 신중하게 실행해야 합니다.

4. FastAPI 시작

uvicorn app.main:app --reload

이제 개발 서버를 http://127.0.0.1:8000에서 사용할 수 있습니다. --reload 옵션을 사용하면 소스 파일이 변경될 때 애플리케이션이 자동으로 다시 로드됩니다.

5. API 문서 열기

http://127.0.0.1:8000/docs를 방문하여 생성된 OpenAPI 엔드포인트를 확인하고 실행해 보세요.

설치 확인

테스트를 실행하려면 backend 디렉터리가 PYTHONPATH에 있어야 합니다. Windows 명령 프롬프트에서 다음을 실행합니다.

set PYTHONPATH=.
python -m pytest

PowerShell에서는 다음을 사용합니다.

$env:PYTHONPATH = "."
python -m pytest

저장소에는 서비스 시작, 재시작, 중지 및 상태 확인을 위한 별도의 PowerShell 제어 파일도 scripts/ 아래에 제공됩니다.

REST API 인증

사용자는 관리자가 생성합니다. 계정이 있으면 로그인 엔드포인트에 사용자 이름과 비밀번호를 제출합니다. 응답에는 인증된 요청에 필요한 토큰이 포함됩니다.

$body = @{
  username = "demo"
  password = "password-123"
} | ConvertTo-Json

$response = Invoke-RestMethod `
  -Method Post `
  -Uri http://127.0.0.1:8000/api/v1/auth/login `
  -ContentType "application/json" `
  -Body $body

$response

반환된 액세스 토큰을 복사하여 Bearer 자격 증명으로 사용합니다. 토큰 권한은 인증된 사용자의 신원과 역할을 따릅니다.

문서 업로드

업로드 엔드포인트는 multipart form data를 사용합니다. 지식 베이스 ID, 선택적 태그, 파일 및 Bearer 토큰을 제공합니다.

$token = "<access_token>"
$knowledgeBaseId = 1

curl.exe `
  -X POST `
  "http://127.0.0.1:8000/api/v1/documents/upload" `
  -H "Authorization: Bearer $token" `
  -F "knowledge_base_id=$knowledgeBaseId" `
  -F "tags=制度,测试" `
  -F "file=@D:\path\to\guide.txt"

이 프로젝트는 개별 업로드와 일괄 업로드를 모두 지원합니다. 업로드된 원본은 로컬 저장소에 유지되며, 지원되는 콘텐츠는 앱 내 리더에서 열 수 있습니다.

폴더 생성 및 사용

폴더 엔드포인트에 지식 베이스 ID와 이름을 전송하여 폴더를 생성합니다.

$body = @{
  knowledge_base_id = 1
  name = "实验方案"
} | ConvertTo-Json

Invoke-RestMethod `
  -Method Post `
  -Uri http://127.0.0.1:8000/api/v1/folders `
  -Headers @{ Authorization = "Bearer $token" } `
  -ContentType "application/json" `
  -Body $body

특정 폴더에 업로드하려면 multipart 업로드 폼에 folder_id를 추가합니다. 웹 인터페이스에서는 폴더를 선택할 때 이 값이 자동으로 추가됩니다.

지식 베이스 선택기의 기본값은 “전체”를 의미하는 全部입니다. 이 보기에는 모든 공개 지식 베이스의 루트 문서와 폴더가 표시됩니다. 폴더를 만들 때는 대화 상자에서 대상 지식 베이스를 선택하세요. 모든 지식 베이스 보기에서 업로드하면 폴더를 선택하지 않은 경우 사용 가능한 첫 번째 지식 베이스를 사용합니다.

브라우저 로컬 미리보기 이해하기

프런트엔드는 인증된 API를 통해 파일을 가져와 브라우저 메모리에 보관하고 로컬에서 렌더링합니다. DOCX, PPTX, XLS, XLSX에는 vue3-office-preview를, PDF에는 @vue3-office/vue-pdf를, Markdown에는 @deot/docs-markdown을 사용합니다. PPTX 렌더링에는 번들로 제공되는 pptx-renderer가 사용됩니다.

이 방식에는 LibreOffice, ONLYOFFICE, Docker 또는 Python 문서 미리보기 SDK가 필요하지 않습니다. 원본 파일은 로컬 스토리지에 그대로 보관됩니다. Markdown 추출과 레거시 .doc, .xls, .ppt 파일의 대체 처리는 계속 백엔드의 책임입니다.

MCP를 통해 AI 에이전트 연결하기

저장소에는 별도의 읽기 전용 MCP 서비스가 포함되어 있습니다. 이 서비스는 FastAPI 애플리케이션의 SQLite 데이터베이스, 로컬 스토리지, JWT 비밀 키 및 문서 리더를 공유합니다. Phase 1에서 사용할 수 있는 도구는 다음과 같습니다.

list_knowledge_bases
list_documents
search_knowledge
get_document
get_document_metadata

MCP 프로세스에서는 업로드, 이동, 삭제 또는 폴더 관리를 수행할 수 없습니다. 문서 접근은 연결된 사용자가 읽을 수 있도록 허용된 범위로 제한됩니다.

MCP 종속성 설치

backend 디렉터리에서 전용 MCP 가상 환경을 만드세요.

cd backend
python -m venv .mcp-venv
.\.mcp-venv\Scripts\python.exe -m pip install -r requirements-mcp.txt

표준 입력 및 출력으로 MCP 실행

API와 동일한 데이터베이스 및 스토리지 설정으로 MCP 프로세스를 구성하세요. 로그인 액세스 토큰을 KB_MCP_TOKEN에 넣은 다음 서버를 시작합니다.

$env:PYTHONPATH = "."
$env:KB_MCP_TOKEN = "<access_token>"
.\.mcp-venv\Scripts\python.exe -m app.mcp_server

로컬 stdio 클라이언트에서는 KB_MCP_TOKEN을 생략할 수 있습니다. 이 경우 에이전트는 사용자의 사용자 이름과 비밀번호로 authenticate 도구를 한 번 호출해야 합니다. 생성된 단기 세션은 MCP 프로세스 메모리에만 존재합니다.

stdio MCP 서비스에 일반적인 print() 호출을 추가하지 마세요. 표준 출력은 프로토콜 메시지에 사용되므로 진단 정보는 표준 오류로 기록해야 합니다.

MCP 스모크 테스트 실행

$env:PYTHONPATH = "."
.\.mcp-venv\Scripts\python.exe scripts\mcp_stdio_smoke.py

Streamable HTTP를 통해 MCP 노출

동일한 MCP 모듈을 시작하기 전에 전송 방식, 수신 주소, 포트, 경로 및 상태 비저장 모드를 설정하세요.

$env:PYTHONPATH = "."
$env:MCP_TRANSPORT = "streamable-http"
$env:MCP_HOST = "0.0.0.0"
$env:MCP_PORT = "8020"
$env:MCP_PATH = "/mcp"
$env:MCP_STATELESS_HTTP = "true"
.\.mcp-venv\Scripts\python.exe -m app.mcp_server

HTTPS 리버스 프록시를 구성한 후 공개 엔드포인트는 https://your-domain/mcp가 될 수 있습니다. 원격 클라이언트는 Authorization: Bearer <access_token>을 전송해야 하며 API 연결과 동일한 보호된 Bearer 자격 증명을 사용해야 합니다.

/mcp-token.html 브라우저 페이지에서는 로그인한 계정의 비밀번호를 읽거나 저장하지 않고 MCP Token을 요청할 수 있습니다. 관리자는 /admin.html을 사용하여 사용자 상태, 역할, 비밀번호 및 사용자별 MCP Token 만료 정책을 관리할 수 있으며, 영구적인 장기 Token도 설정할 수 있습니다.

고급 운영 팁

API와 MCP 설정을 일치시키세요. 두 서비스는 동일한 SQLite 데이터베이스와 스토리지 경로를 가리키고 동일한 JWT 비밀 키를 사용해야 합니다.
최소 권한 ID를 사용하세요. MCP 에이전트는 토큰 사용자에게 허용된 문서 읽기 범위를 상속합니다.
Bearer 토큰을 보호하세요. API 또는 MCP 자격 증명을 소스 관리, 로그 또는 일반 콘솔 출력에 저장하지 마세요.
stdio 프로토콜을 유지하세요. MCP 진단 정보는 표준 출력이 아니라 표준 오류로 전송하세요.
원격에서는 HTTPS를 사용하세요. 로컬 머신 외부에 노출하기 전에 Streamable HTTP 엔드포인트를 HTTPS 리버스 프록시 뒤에 배치하세요.
Phase 1의 범위를 기억하세요. Docker Compose, PostgreSQL 및 객체 스토리지는 현재 런타임 요구 사항이 아니라 마이그레이션 대상입니다.
소유권 제한을 확인하세요. 문서 편집, 소프트 삭제, 복원, 폴더 이름 변경 및 빈 폴더 삭제는 소유자만 수행할 수 있습니다.
생성된 API 문서를 사용하세요. /docs 페이지는 여기에 제시된 예시 외에 사용 가능한 요청 필드와 응답을 확인하는 가장 직접적인 방법입니다.

결론

Knowledge Base Phase 1은 인증된 파일 구성, 미리보기, 검색 및 에이전트 접근을 위한 실용적인 로컬 기반을 제공합니다. Python, SQLite 및 로컬 스토리지만으로 서비스를 초기화하고, 구조화된 문서 컬렉션을 업로드하며, 폴더와 메타데이터를 관리하고, 로컬 stdio 또는 원격 Streamable HTTP MCP 전송을 통해 읽기 전용 지식 도구를 안전하게 노출할 수 있습니다.