AI 에이전트는 세션 간의 모든 것을 잊어버립니다. Connapse가 이를 해결합니다.

새로운 대화를 시작할 때마다 AI 에이전트는 과거 연구에 대한 기억, 문서에 대한 접근 권한, 축적된 지식 없이 처음부터 다시 시작합니다. Connapse는 에이전트에게 지속적이고 검색 가능한 메모리를 제공하는 오픈 소스 지식 백엔드입니다. 문서를 업로드하거나 기존 Amazon S3 버킷, Azure Blob Storage 컨테이너 또는 로컬 파일 시스템을 연결하세요. 에이전트는 11개의 MCP 도구, REST API 또는 CLI를 통해 연구 자료를 쿼리하고 구축합니다. 컨테이너 격리, 하이브리드 검색(벡터 + 키워드), 자체 호스팅 및 비공개 환경을 지원합니다. Docker를 사용하여 60초 만에 배포하세요. .NET 10 기반으로 구축되었습니다.

AI 에이전트는 MCP 서버를 통해 지식 베이스를 쿼리하고, 문서의 출처 인용이 포함된 구조화된 답변을 받습니다.

임베딩 제공자 전환, 청킹 매개변수 조정, 검색 설정 구성을 재시작 없이 런타임에 수행하세요.

📦 빠른 시작

git clone https://github.com/Destrayon/Connapse.git && cd Connapse && docker-compose up -d
# Open http://localhost:5001

사전 요구 사항

Docker 및 Docker Compose
.NET 10 SDK (개발용)
(선택 사항) 로컬 임베딩을 위한 Ollama

Docker Compose로 실행

# Clone the repository
git clone https://github.com/Destrayon/Connapse.git
cd Connapse

# Set required auth environment variables (or use a .env file)
export CONNAPSE_ADMIN_EMAIL=admin@example.com
export CONNAPSE_ADMIN_PASSWORD=YourSecurePassword123!
export Identity__Jwt__Secret=$(openssl rand -base64 64)

# Start all services (PostgreSQL, MinIO, Web App)
docker-compose up -d

# Open http://localhost:5001 — log in with the admin credentials above

첫 실행 시 다음 작업이 수행됩니다:

Docker 이미지 풀 (~2-5분)
pgvector 확장이 포함된 PostgreSQL 초기화 및 EF Core 마이그레이션 실행
MinIO 버킷 생성
관리자 계정 시드(환경 변수 사용) 및 웹 애플리케이션 시작

개발 설정

# Start infrastructure only (database + object storage)
docker-compose up -d postgres minio

# Run the web app locally
dotnet run --project src/Connapse.Web

# Run all tests
dotnet test

# Run just unit tests
dotnet test --filter "Category=Unit"

CLI 사용

CLI 설치(옵션 중 선택):

# Option A: .NET Global Tool (requires .NET 10)
dotnet tool install -g Connapse.CLI

# Option B: Download native binary from GitHub Releases (no .NET required)
# https://github.com/Destrayon/Connapse/releases

기본 사용법:

# Authenticate first
connapse auth login --url https://localhost:5001

# Create a container (project)
connapse container create my-project --description "My knowledge base"

# Upload files
connapse upload ./documents --container my-project

# Search
connapse search "your query" --container my-project

# Update to latest release (--pre to include alpha/pre-release builds)
connapse update
connapse update --pre

Claude와 함께 사용 (MCP)

Connapse는 Claude 및 모든 MCP 클라이언트와 통합하기 위한 모델 컨텍스트 프로토콜(MCP) 서버를 포함합니다.

설정: 웹 UI(설정 → 에이전트 API 키) 또는 CLI(connapse auth agent-key create)를 통해 에이전트 API 키를 생성한 다음, 클라이언트용 구성 스니펫을 추가하세요:

claude mcp add connapse --transport streamable-http http://localhost:5001/mcp --header "X-Agent-Api-Key: YOUR_API_KEY"

claude_desktop_config.json에 추가:

{
  "mcpServers": {
    "connapse": {
      "transport": "streamable-http",
      "url": "http://localhost:5001/mcp",
      "headers": {
        "X-Agent-Api-Key": "YOUR_API_KEY"
      }
    }
  }
}

.vscode/settings.json(VS Code) 또는 Cursor MCP 구성에 추가:

{
  "mcp": {
    "servers": {
      "connapse": {
        "transport": "streamable-http",
        "url": "http://localhost:5001/mcp",
        "headers": {
          "X-Agent-Api-Key": "${input:connapseApiKey}"
        }
      }
    }
  }
}

VS Code는 처음 사용할 때 API 키를 묻는 메시지를 표시합니다.

MCP 서버는 11개의 도구를 제공합니다:

도구	설명
`container_create`	파일 정리를 위한 새 컨테이너 생성
`container_list`	문서 개수가 포함된 모든 컨테이너 목록
`container_delete`	컨테이너 삭제
`container_stats`	컨테이너 통계 확인 (문서, 청크, 스토리지, 임베딩)
`upload_file`	컨테이너에 단일 파일 업로드
`bulk_upload`	한 번에 최대 100개의 파일 업로드
`list_files`	경로의 파일 및 폴더 목록
`get_document`	문서의 전체 파싱된 텍스트 내용 검색
`delete_file`	컨테이너에서 단일 파일 삭제
`bulk_delete`	한 번에 최대 100개의 파일 삭제
`search_knowledge`	컨테이너 내 의미론적, 키워드 또는 하이브리드 검색

전체 참조: 매개변수 테이블, 반환 형식, 오류 사례 및 사용 예시는 docs/mcp-tools.md를 참조하세요.

쓰기 보호: Amazon S3 및 Azure Blob Storage 컨테이너는 읽기 전용입니다(소스에서 동기화). 파일 시스템 컨테이너는 컨테이너별 권한 플래그를 따릅니다. 쓰기가 차단된 컨테이너에 대해 업로드 및 삭제 도구를 사용하면 오류가 반환됩니다.

"내 아키텍처 노트를 위해 'project-research'라는 컨테이너를 만들어줘"
"다운로드 폴더의 모든 PDF를 project-research 컨테이너에 업로드해줘"
"project-research 컨테이너에서 속도 제한 전략에 대한 정보를 검색해줘"
"project-research 컨테이너의 /notes/ 폴더에 있는 모든 파일 목록을 보여줘"
"project-research에서 distributed-systems-notes.md의 전체 텍스트를 가져와줘"
"project-research에서 meeting-2026-03-14.md를 삭제하고 이 업데이트된 버전을 업로드해줘"
"project-research의 /drafts/ 폴더에 있는 모든 파일을 삭제해줘"
"project-research 컨테이너에 문서와 청크가 몇 개나 있니?"

localhost:5001 연결 거부 — Docker가 실행 중이지 않거나 포트 충돌입니다. docker compose ps 및 docker compose logs web을 확인하세요.

401 Unauthorized / API 키가 작동하지 않음 — 설정 > 에이전트 API 키에서 키를 확인하세요. 키는 생성 시 한 번만 표시됩니다.

Claude에 도구가 나타나지 않음 — 구성 변경 후 MCP 클라이언트를 다시 시작하세요. curl http://localhost:5001/mcp로 엔드포인트를 확인하세요.

업로드 실패 또는 시간 초과 — 파일 형식이 허용 목록에 있는지 확인하세요. 최대 파일 크기는 서버 구성에 따라 다릅니다.

검색 결과 없음 — 업로드 후 문서가 임베딩될 시간이 필요합니다. 컨테이너 통계에서 임베딩 진행 상황을 확인하세요.

🚀 기능

🗂️ 컨테이너 격리 지식 — 각 프로젝트는 고유한 벡터 인덱스, 스토리지 커넥터 및 검색 구성을 가집니다. 프로젝트, 팀 또는 클라이언트 간의 데이터 혼선이 없습니다.
🔍 하이브리드 검색 — 벡터 유사도 + 키워드 전체 텍스트 검색을 구성 가능한 융합(convex combination, DBSF, AutoCut)으로 제공합니다. 순수 벡터 검색이 놓치는 결과까지 찾아냅니다.
🧠 다중 제공자 AI — 런타임에 컨테이너별로 Ollama, OpenAI, Azure OpenAI, Anthropic 간에 임베딩 및 LLM을 전환할 수 있습니다(재시작 불필요).
🔌 기존 스토리지 인덱싱 — MinIO, 로컬 파일 시스템(실시간 파일 감시), Amazon S3(IAM 인증) 또는 Azure Blob Storage(관리 ID)를 연결하세요. 파일은 원래 위치에 유지됩니다.
🤖 4가지 접근 방식 — 웹 UI, REST API, CLI(네이티브 바이너리), MCP 서버(Claude용 11개 도구). 사람, 스크립트, AI 에이전트 모두를 위해 구축되었습니다.
🔐 엔터프라이즈 인증 — AWS IAM Identity Center 및 Azure AD ID 연결을 포함한 다중 계층 RBAC(쿠키 + OAuth 2.1 + PAT + JWT). 클라우드 권한이 진실의 원천입니다.
🐳 원클릭 배포 — PostgreSQL + pgvector, MinIO 및 선택적 Ollama가 포함된 Docker Compose. 구조화된 감사 로깅 및 속도 제한이 내장되어 있습니다.

📄 다중 형식 수집: PDF, Office 문서, Markdown, 일반 텍스트 — 자동으로 파싱, 청킹 및 임베딩
⚡ 실시간 처리: SignalR을 통한 실시간 진행 상황 업데이트와 함께 백그라운드 수집
🎛️ 런타임 구성: 재시작 없이 컨테이너별로 청킹 전략, 임베딩 모델 및 검색 설정 변경
☁️ 클라우드 ID 연결: AWS IAM Identity Center(기기 인증 흐름) + Azure AD(OAuth2+PKCE) 및 IAM 기반 범위 적용
👥 초대 전용 액세스: 4가지 역할(관리자 / 편집자 / 뷰어 / 에이전트)을 갖춘 관리자 제어 사용자 등록
🤖 에이전트 관리: API 키 수명 주기, 범위 지정 권한 및 감사 추적을 갖춘 전용 에이전트 엔티티
📋 감사 로깅: 업로드, 삭제, 컨테이너 작업 및 인증 이벤트에 대한 구조화된 감사 추적
📦 CLI 배포: 네이티브 독립형 바이너리(Windows/Linux/macOS) 및 NuGet을 통한 .NET 글로벌 도구
🔄 교차 모델 검색: 프로젝트 중간에 임베딩 모델 전환 — 레거시 벡터에 대한 자동 의미론적→하이브리드 폴백

🎯 Connapse는 누구를 위한 것인가요?

AI 에이전트 개발자: 에이전트가 쿼리하고 구축할 수 있는 지식 백엔드가 필요한 경우 — 연구 업로드, 자료 큐레이션, MCP 또는 REST API를 통한 검색
.NET / Azure 팀: 기존 스택 및 클라우드 ID에 맞는 RAG 플랫폼을 원하는 경우
엔터프라이즈 팀: 적절한 RBAC 및 감사 추적이 포함된 프로젝트 격리 지식 베이스가 필요한 경우
파일 재업로드에 지친 분들: 기존 Amazon S3/Azure Blob Storage/파일 시스템 스토리지에 Connapse를 연결하세요

이 프로젝트는 활발히 개발 중(v0.3.2)이며 프로덕션 준비 단계에 접근하고 있습니다.

v0.3.x는 IAM 기반 액세스 제어, 다중 제공자 임베딩 및 LLM 지원, 클라우드 ID 연결(AWS SSO + Azure AD), 속도 제한을 갖춘 클라우드 커넥터 아키텍처를 추가합니다.

✅ 인증 및 권한 부여 (v0.2.0)
✅ 역할 기반 액세스 제어 (관리자 / 편집자 / 뷰어 / 에이전트)
✅ 감사 로깅
✅ 클라우드 ID 연결 — AWS IAM Identity Center + Azure AD OAuth2+PKCE (v0.3.0)
✅ IAM 기반 범위 적용 — 클라우드 권한이 진실의 원천 (v0.3.0)
✅ 속도 제한 — 사용자별 및 IP별 정책이 포함된 ASP.NET Core 미들웨어 (v0.3.2)
⚠️ 프로덕션 환경에서 강력한 Identity__Jwt__Secret 설정 — 배포 가이드 참조

전체 보안 정책은 SECURITY.md를 참조하세요.

🏗️ 아키텍처

┌──────────────────────────────────────────────────────────────────────┐
│                         Access Surfaces                              │
│  Web UI (Blazor)  │  REST API  │  CLI  │  MCP Server                │
└─────────────┬────────────────────────────────────────────────────────┘
              │
┌─────────────▼────────────────────────────────────────────────────────┐
│                       Core Services Layer                            │
│  Document Store  │  Vector Store  │  Search  │  Ingestion           │
└─────────────┬────────────────────────────────────────────────────────┘
              │
┌─────────────▼────────────────────────────────────────────────────────┐
│                        Connectors Layer                              │
│  MinIO  │  Filesystem  │  Amazon S3  │  Azure Blob Storage          │
└─────────────┬────────────────────────────────────────────────────────┘
              │
┌─────────────▼────────────────────────────────────────────────────────┐
│                        Infrastructure                                │
│  PostgreSQL+pgvector  │  MinIO (S3)  │  Ollama (optional)           │
└──────────────────────────────────────────────────────────────────────┘

데이터 흐름: 업로드 → 검색

[Upload] → [Parse] → [Chunk] → [Embed] → [Store] → [Searchable]
              ↓
         [Metadata]
              ↓
        [Document Store]

목표: 업로드부터 검색 가능까지 < 30초.

핵심 기술:

데이터베이스: PostgreSQL 17 + 벡터 임베딩용 pgvector
객체 스토리지: 관리형 스토리지 추상화 — 기본적으로 MinIO(S3 호환), 배포별로 재정의 가능
백엔드: ASP.NET Core 10 Minimal API
**프론트

Connapse