MCP-RAG

✨100% AI 작성

AI 클라이언트를 위한 서비스 우선 RAG 서비스로, 현재 FastAPI HTTP 서비스와 Streamable HTTP MCP 엔드포인트를 중심으로 제공됩니다.

현재 코드는 통합 백엔드 셸을 제공합니다:

• FastAPI HTTP 서비스

• Streamable HTTP MCP

• 공유 런타임, 설정 핫 리로드, 인증, 속도 제한, 할당량, 관측 가능성

• 지식 베이스 레지스트리 기반 검색 및 문서 관리

현재 기능

• 문서 가져오기: 텍스트 직접 추가 및 txt, md, pdf, docx 업로드 지원

• 검색: 벡터 검색 + 키워드 검색 결합

• 질의응답: /search, /chat, MCP rag_ask

• 다중 지식 베이스: 단일 지식 베이스 및 kb_ids를 통한 다중 지식 베이스 통합 검색/대화 지원

• 지식 베이스 범위: public 및 agent_private

• 테넌트 컨텍스트: base_collection + user_id + agent_id

• 런타임 관리: API 키, 메모리 속도 제한, 업로드/인덱싱 할당량, 요청 수준 검색 캐시

• 공급자 관리: 공급자 예산, 서킷 브레이커, 폴백

• 관측 가능성: /health, /ready, /metrics

• 프론트엔드: 내장 단일 페이지 관리 패널 /app

아키텍처

주요 링크:

HTTP / MCP
  -> app_factory.py
  -> http_server.py / mcp_server.py
  -> context.py
  -> service_facade.py
  -> services/
       - runtime.py
       - indexing_service.py
       - retrieval_service.py
       - chat_service.py
  -> knowledge_bases.py
  -> core/indexing/
  -> retrieval/

주요 파일:

• src/mcp_rag/cli.py: CLI 진입점, serve 및 init 제공

• src/mcp_rag/main.py: HTTP 서비스 시작 진입점

• src/mcp_rag/http_server.py: HTTP API, SPA 진입점, Streamable HTTP MCP 마운트

• src/mcp_rag/mcp_server.py: MCP 도구 정의 및 rag_ask

• src/mcp_rag/app_factory.py: 앱 컨텍스트, 런타임, 가드레일 통합 조립

• src/mcp_rag/knowledge_bases.py: 지식 베이스 레지스트리 및 기본 지식 베이스 해석

• src/mcp_rag/config.py: 설정 모델, JSON/SQLite 영속성, 핫 리로드

환경 요구 사항

• Python >= 3.13

• uv

설치

CLI 설치:

uv tool install mcp-rag

설치 후 바로 실행:

mcp-rag serve

저장소 내 개발:

uv sync

로컬 임베딩이 필요한 경우:

uv sync --extra local-embeddings

경계 사항:

• uv tool install mcp-rag를 사용하는 사용자는 Node.js나 pnpm이 필요하지 않습니다.

• pnpm은 프론트엔드 빌드 유지보수용이며, 서비스 런타임 의존성이 아닙니다.

시작 및 초기화

서비스 시작:

uv run mcp-rag serve

데이터 디렉토리 초기화:

uv run mcp-rag init --data-dir ./data

기본 포트는 8060이며, 서비스는 기본적으로 0.0.0.0:8060에서 수신 대기합니다.

주요 진입점:

• 관리 패널: http://127.0.0.1:8060/app

• API 문서: http://127.0.0.1:8060/docs

• MCP 엔드포인트: http://127.0.0.1:8060/mcp

호환 진입점:

• /는 /app으로 리다이렉트됩니다.

• /doc는 /docs로 리다이렉트됩니다.

• /documents-page는 /app/documents로 리다이렉트됩니다.

• /config-page는 /app/config로 리다이렉트됩니다.

최초 시작 동작:

• ./data/config.json이 없으면 설정을 읽을 때 기본값을 먼저 사용합니다.

• 서비스 시작 시 ensure_config_file()이 호출되어 기본 설정이 디스크에 기록됩니다.

• 데이터 디렉토리 내의 ./data/chroma 및 관련 SQLite 파일은 필요에 따라 생성됩니다.

프론트엔드 및 정적 리소스

배포 패키지는 src/mcp_rag/static/을 wheel / sdist에 함께 포함합니다.

즉:

• 사용자가 uv tool install mcp-rag를 설치하면 바로 /app에 접속할 수 있습니다.

• 별도의 프론트엔드 빌드나 Node.js가 필요하지 않습니다.

• 프론트엔드 유지보수자는 릴리스 전에 최신 정적 리소스를 생성해야 합니다.

프론트엔드 소스 코드는 frontend/에 있으며, 빌드 결과물은 src/mcp_rag/static/app으로 출력됩니다.

일반적인 프로세스:

cd frontend
pnpm install
pnpm build

지식 베이스 모델

현재 프로젝트는 더 이상 단순 collection으로 데이터를 구성하지 않고, 지식 베이스 레지스트리를 중심으로 합니다.

지식 베이스 특징:

• 영속적 레지스트리는 knowledge_base_db_path가 가리키는 SQLite 파일에 저장됩니다.

• 기본적으로 공용 지식 베이스가 존재하도록 보장합니다.

• user_id + agent_id가 전달되면 해당되는 기본 agent_private 지식 베이스가 존재하도록 보장합니다.

• 새 지식 베이스 생성 시 kb_<id>와 같은 안정적인 내부 컬렉션 이름이 할당됩니다.

인터페이스 계층은 이전 호출 방식과의 호환성을 위해 collection 매개변수를 유지합니다. 현재 실제 동작은 다음과 같습니다:

• kb_id를 명시적으로 전달할 수 있습니다.

• 기존 collection을 계속 전달할 수도 있습니다.

• 서비스는 요청을 구체적인 지식 베이스와 실제 컬렉션 이름으로 해석합니다.

HTTP 인터페이스

시스템 인터페이스:

• GET /health

• GET /ready

• GET /metrics

설정 인터페이스:

• GET /config

• POST /config

• POST /config/bulk

• POST /config/reset

• POST /config/reload

공급자 인터페이스:

• GET /providers/{provider}/models

지식 베이스 인터페이스:

• GET /collections

• GET /knowledge-bases

• POST /knowledge-bases

문서 인터페이스:

• POST /add-document

• POST /upload-files

• GET /list-documents

• DELETE /delete-document

• GET /list-files

• DELETE /delete-file

검색 및 질의응답:

• GET /search

• POST /chat

MCP 디버깅 인터페이스:

• GET /debug/mcp/tools

• POST /debug/mcp/call

참고 사항:

• /search와 /chat은 kb_id를 지원합니다.

• /search와 /chat은 다중 지식 베이스 통합을 위한 kb_ids도 지원합니다.

• /upload-files는 multipart/form-data를 사용합니다.

• /delete-document와 /delete-file은 요청 본문을 통해 삭제 매개변수를 전달합니다.

보안 정책이 활성화된 경우, API 키는 다음 방식으로 전달할 수 있습니다:

• HTTP Header: x-api-key

• Header: Authorization: Bearer <token>

• 쿼리 매개변수, JSON 본문 또는 폼의 api_key

MCP

현재 주요 형태는 Streamable HTTP MCP입니다:

{
  "mcpServers": {
    "rag": {
      "url": "http://127.0.0.1:8060/mcp"
    }
  }
}

구현된 MCP 도구:

• rag_ask

rag_ask 주요 매개변수:

• query

• mode: raw 또는 summary

• collection

• kb_id

• scope

• limit

• threshold

• tenant

• user_id / agent_id

• _user_id / _agent_id

• api_key

• request_id

• trace_id

예시:

{
  "name": "rag_ask",
  "arguments": {
    "query": "FastAPI 是什么",
    "kb_id": 1,
    "mode": "summary",
    "limit": 5
  }
}

설정

기본 설정 파일:

./data/config.json

기본 지식 베이스 데이터베이스:

./data/knowledge_bases.sqlite3

현재 설정의 중요한 변경 사항:

• 일반 실행 설정은 config.json에 저장됩니다.

• 공급자 관련 설정은 config.json에 완전히 다시 쓰지 않고 SQLite에 영속화됩니다.

즉, 다음 필드들은 SQLite의 service_provider_settings에 저장됩니다:

• embedding_provider

• embedding_fallback_provider

• provider_configs

• llm_provider

• llm_fallback_provider

• llm_model

• llm_base_url

• llm_api_key

나머지 설정은 config.json에 유지됩니다. 예:

{
  "http_port": 8060,
  "chroma_persist_directory": "./data/chroma",
  "knowledge_base_db_path": "./data/knowledge_bases.sqlite3",
  "enable_llm_summary": false,
  "security": {
    "enabled": false,
    "allow_anonymous": true,
    "api_keys": [],
    "tenant_api_keys": {}
  },
  "rate_limit": {
    "requests_per_window": 120,
    "window_seconds": 60,
    "burst": 30
  },
  "quotas": {
    "max_upload_files": 20,
    "max_upload_bytes": 52428800,
    "max_upload_file_bytes": 10485760,
    "max_index_documents": 500,
    "max_index_chunks": 2000,
    "max_index_chars": 500000
  },
  "cache": {
    "enabled": false,
    "max_entries": 256,
    "ttl_seconds": 300
  },
  "provider_budget": {
    "enabled": true
  }
}

현재 내장 공급자 관련 기능:

• 임베딩 공급자 기본값은 zhipu입니다.

• LLM 공급자 기본값은 doubao입니다.

• 내장 공급자 설정에는 doubao, zhipu, aliyun이 포함됩니다.

• qwen / dashscope는 aliyun으로 정규화됩니다.

• /providers/{provider}/models는 OpenAI 호환 모델 서비스에서 모델 목록을 가져오는 것을 지원합니다.

• 로컬 임베딩은 m3e-small 및 e5-small을 지원합니다.

• LLM은 추가로 ollama를 지원합니다.

핫 리로드 및 런타임 새로고침

핫 리로드 동작:

• /config, /config/bulk, /config/reset, /config/reload를 통해 수정되면 런타임이 즉시 새로고침됩니다.

• 요청이 들어올 때 reload_if_changed()를 통해 디스크 설정 변경 여부를 감지합니다.

• 공급자 설정이나 검색 설정이 변경되면 관련 런타임 의존성을 재구축하고 검색 캐시를 정리합니다.

Readiness 및 Metrics

• /health는 상태 요약, 런타임 스냅샷 및 config_revision을 반환합니다.

• /ready는 부트스트랩이 완료되지 않았거나 주요 의존성이 준비되지 않은 경우 503을 반환합니다.

• /metrics는 작업/공급자별로 집계된 관측 지표를 반환합니다.

현재 readiness 스냅샷 포함 항목:

• document_processor

• embedding_model

• vector_store

• hybrid_service

• llm_model

• retrieval_cache

• provider_budget

테스트

전체 테스트 실행:

uv run python -m unittest discover -s tests

컴파일 검사:

uv run python -m compileall src

현재 테스트 범위:

• 설정 기본값, 디스크 리로드 및 공급자 설정 마이그레이션

• HTTP 셸 및 MCP 셸 동작

• 요청 컨텍스트 / 테넌트 해석

• 요청 수준 검색 캐시

• 공급자 예산 / 폴백

• readiness / health / metrics

• 패키징 메타데이터 및 정적 리소스

라이선스

MIT