GreatScottyMac/context-portal

IDE 및 기타 인터페이스 내의 AI 어시스턴트와 개발자 도구가 사용할 수 있도록 설계된, 구조화된 프로젝트 컨텍스트 (Context) 관리를 위한 데이터베이스 기반 Model Context Protocol (MCP) 서버입니다.

Context Portal (ConPort)은 귀하의 프로젝트를 위한 **메모리 뱅크 (Memory Bank)**입니다. 이 도구는 결정 사항, 작업, 아키텍처 패턴과 같은 중요한 정보를 구조화된 방식으로 저장함으로써 AI 어시스턴트가 귀하의 특정 소프트웨어 프로젝트를 더 잘 이해할 수 있도록 돕습니다. AI가 쉽게 접근하여 더 정확하고 유용한 응답을 제공할 수 있도록 프로젝트 전용 지식 베이스 (Knowledge Base)를 구축한다고 생각하면 됩니다.

주요 기능:

• 프로젝트 결정 사항, 진행 상황 및 시스템 설계를 추적합니다.
• 사용자 정의 프로젝트 데이터 (용어집 또는 사양 등)를 저장합니다.
• AI가 관련 프로젝트 정보를 빠르게 찾을 수 있도록 돕습니다 (스마트 검색과 유사).
• AI가 더 나은 응답을 위해 프로젝트 컨텍스트를 사용할 수 있도록 합니다 (RAG).
• 단순한 텍스트 파일 기반의 메모리 뱅크에 비해 컨텍스트를 관리, 검색 및 업데이트하는 데 더 효율적입니다.

ConPort는 AI 어시스턴트가 다양한 유형의 프로젝트 컨텍스트를 저장, 검색 및 관리할 수 있는 강력하고 구조화된 방법을 제공합니다. 이는 결정 사항, 진행 상황, 아키텍처와 같은 엔티티 (Entity) 및 그 관계를 포착하여 효과적으로 **프로젝트 전용 지식 그래프 (Project-specific Knowledge Graph)**를 구축합니다. 시맨틱 검색 (Semantic Search)을 위한 **벡터 임베딩 (Vector Embeddings)**으로 강화된 이 구조화된 지식 베이스는 **검색 증강 생성 (RAG, Retrieval Augmented Generation)**을 위한 강력한 백엔드 역할을 수행하며, 이를 통해 AI 어시스턴트가 정확하고 최신 정보를 사용하여 더욱 컨텍스트를 잘 파악한 정확한 응답을 제공할 수 있게 합니다.

ConPort는 더 신뢰할 수 있고 쿼리가 가능한 데이터베이스 백엔드 (워크스페이스당 하나의 SQLite)를 제공함으로써 기존의 파일 기반 컨텍스트 관리 시스템을 대체합니다. ConPort는 MCP를 지원하는 다양한 IDE 및 클라이언트 인터페이스와 호환되는 범용 컨텍스트 백엔드로 설계되었습니다.

주요 특징은 다음과 같습니다:

• SQLite를 사용한 구조화된 컨텍스트 저장 (워크스페이스당 하나의 DB가 자동으로 생성됨).
• MCP 서버 (context_portal_mcp)

Python/FastAPI로 구축되었습니다. - 상호작용을 위한 정의된 MCP 도구 세트 제공 (아래 "사용 가능한 ConPort 도구" 참조).

• workspace_id를 통한 멀티 워크스페이스 (Multi-workspace) 지원.
• 주요 배포 모드: IDE와의 긴밀한 통합을 위한 STDIO.
• 컨텍스트 항목 간의 명시적 관계를 가진 동적인 프로젝트 지식 그래프 (project knowledge graph) 구축 가능.
• 고급 RAG를 지원하기 위한 벡터 데이터 저장 (vector data storage) 및 시맨틱 검색 (semantic search) 기능 포함.
• **검색 증강 생성 (Retrieval Augmented Generation, RAG)**을 위한 이상적인 백엔드 역할을 수행하며, AI에게 정밀하고 쿼리가 가능한 프로젝트 메모리를 제공.
• 호환 가능한 LLM 제공업체와 함께 AI 어시스턴트가 **프롬프트 캐싱 (prompt caching)**에 활용할 수 있는 구조화된 컨텍스트 제공.
• **Alembic 마이그레이션 (Alembic migrations)**을 사용하여 데이터베이스 스키마 진화를 관리하며, 원활한 업데이트와 데이터 무결성을 보장.

시작하기 전에 다음 항목들이 설치되어 있는지 확인하십시오:

Python: 버전 3.8 이상을 권장합니다.

• Python 다운로드
• 설치 시 Python이 시스템의 PATH에 추가되었는지 확인하십시오 (특히 Windows의 경우).

uv: (강력 권장) 빠르고 효율적인 Python 환경 및 패키지 관리자입니다. uv를 사용하면 가상 환경 생성 및 의존성 설치가 크게 간소화됩니다.

ConPort를 설치하고 실행하는 권장 방법은 uvx를 사용하여 PyPI에서 패키지를 직접 실행하는 것입니다. 이 방법을 사용하면 가상 환경을 수동으로 생성하고 관리할 필요가 없습니다.

MCP 클라이언트 설정(예: mcp_settings.json)에서 다음 구성을 사용하십시오:

{
"mcpServers": {
"conport": {
...

• command: uvx가 환경 관리를 대신 처리합니다.
• args: ConPort 서버를 실행하기 위한 인자들을 포함합니다.
• ${workspaceFolder}: 이 IDE 변수는 현재 프로젝트 워크스페이스의 절대 경로를 자동으로 제공하는 데 사용됩니다.
• --log-file: (선택 사항) 서버 로그가 기록될 파일 경로입니다. 제공되지 않으면 로그는 stderr (콘솔)로 전달됩니다. 지속적인 로깅 및 서버 동작 디버깅에 유용합니다.
• --log-level

: 선택 사항: 서버의 최소 로깅 레벨 (logging level)을 설정합니다. 유효한 선택지는 DEBUG, INFO, WARNING, ERROR, CRITICAL입니다. 기본값은 INFO입니다. 개발 중이거나 문제 해결 (troubleshooting) 시 상세한 출력을 원하면 DEBUG로 설정하세요.

중요: 많은 IDE들은 MCP 서버를 실행할 때 ${workspaceFolder}를 확장하지 않습니다. 다음의 안전한 옵션 중 하나를 사용하세요:

• --workspace_id에 절대 경로를 제공합니다.
• 실행 시 --workspace_id를 생략하고, 호출 시마다 전달되는 workspace_id에 의존합니다 (클라이언트가 매 호출마다 이를 제공하는 경우 권장됨).

대체 설정 방식 (--workspace_id를 실행 시 생략하는 경우):

{
"mcpServers": {
"conport": {
...

--workspace_id를 생략하면, 서버는 사전 초기화 (pre-initialization)를 건너뛰고 해당 호출에서 제공된 workspace_id를 사용하여 첫 번째 도구 호출 (tool call) 시 데이터베이스를 초기화합니다.

ConPort를 개발하고 테스트하는 가장 적절한 방법은 위의 설정을 사용하여 IDE에서 MCP 서버로 실행하는 것입니다. 이를 통해 STDIO 모드와 실제 클라이언트 동작을 테스트할 수 있습니다.

로컬 체크아웃 (local checkout) 및 가상 환경 (virtualenv)에서 실행해야 하는 경우, MCP 클라이언트가 uv run 및 .venv/bin/python을 통해 개발 서버를 실행하도록 구성할 수 있습니다:

{
"mcpServers": {
"conport": {
...

참고 사항:

• --directory를 리포지토리 경로로 설정하세요. 이렇게 하면 로컬 체크아웃 및 venv 인터프리터를 사용합니다. - 로그는 DEBUG 상세도로 ./logs/conport-dev.log에 저장됩니다.

Git 리포지토리를 통해 개발 또는 기여를 위한 환경을 설정하세요.

• 리포지토리 클론 (Clone the repository): git clone https://github.com/GreatScottyMac/context-portal.git cd context-portal
• 가상 환경 생성 (Create a virtual environment): uv venv. 셸의 표준 활성화 방식(예: macOS/Linux의 경우 source .venv/bin/activate)을 사용하여 활성화하세요.
• 의존성 설치 (Install dependencies): uv pip install -r requirements.txt
• IDE에서 실행 (권장) (Run in your IDE (recommended)): "uvx Configuration" 또는 개발용 uv run을 사용하여 IDE의 MCP 설정을 구성하세요.

위에서 보여준 설정입니다. 이것은 STDIO 모드에서 ConPort를 테스트하는 가장 대표적인 방법입니다. -
선택 사항: CLI 도움말
uv run python src/context_portal_mcp/main.py --help

참고 사항:

• --workspace_id 동작 및 IDE 경로 처리 방식에 대해서는 위

• 귀하의 LLM 에이전트 환경과 관련된 전략(strategy) 파일을 식별합니다.

• 해당 파일의 전체 내용을 복사합니다.

• 이를 LLM의 커스텀 인스트럭션(custom instructions) 또는 시스템 프롬프트(system prompt) 영역에 붙여넣습니다. 방법은 LLM 플랫폼마다 다릅니다 (IDE 확장 프로그램 설정, 웹 UI, API 구성 등).

이 지침을 통해 LLM은 다음과 같은 지식을 갖추게 됩니다:

• ConPort로부터 컨텍스트(context)를 초기화하고 로드합니다.
• 새로운 정보(결정 사항, 진행 상황 등)로 ConPort를 업데이트합니다.
• 커스텀 데이터 및 관계를 관리합니다.
• workspace_id의 중요성을 이해합니다.

세션 시작을 위한 중요한 팁: LLM 에이전트가 컨텍스트를 올바르게 초기화하고 로드하도록 보장하기 위해(특히 첫 메시지에서 커스텀 인스트럭션을 항상 엄격하게 준수하지 않을 수 있는 인터페이스의 경우), 다음과 같은 명확한 지시어로 상호작용을 시작하는 것이 좋습니다:
Initialize according to custom instructions. (커스텀 인스트럭션에 따라 초기화하세요.)

이는 에이전트가 전략 파일에 정의된 대로 ConPort 초기화 시퀀스를 수행하도록 유도하는 데 도움이 될 수 있습니다.

이 저장소에는 스프린트 계획(sprint planning) 및 운영 흐름(operational flows)에 초점을 맞춘 새로운 전략/문서 세트가 포함되어 있습니다:

conport-custom-instructions/mem4sprint.md
— 플랫 카테고리(flat categories) 및 유효한 FTS 접두사(prefixes) 사용을 위한 간결한 가이드 및 패턴.

conport-custom-instructions/mem4sprint.schema_and_templates.md
— 메타 스키마(meta schema), 컴팩트 스타터(compact starters), FTS 쿼리 규칙 및 최소한의 운영 호출 레시피(operational call recipes).

주요 하이라이트:

• 플랫 카테고리 모델 (예: artifacts, rfc_doc, retrospective, ProjectGlossary, critical_settings).
• 유효한 FTS5 접두사만 사용: 커스텀 데이터의 경우 category:, key:, value_text:; 결정 사항의 경우 summary:, rationale:, implementation_details:, tags:.
• 핸들러 계층(handler-layer) 쿼리 정규화; 데이터베이스 계층은 변경되지 않음.

릴리스 노트 요약:

• 플랫 카테고리 및 명시적인 FTS 규칙이 포함된 mem4sprint 전략/문서 추가.
• 예제를 단순화하고 최소한의 운영 호출 레시피 포함.
• 문서에서 MCP를 위한 IDE 워크스페이스 경로 처리 방식 명시.

새로운 프로젝트 워크스페이스나 기존 프로젝트 워크스페이스에서 ConPort를 처음 사용할 때, ConPort 데이터베이스(context_portal/context.db)가 존재하지 않으면 서버에 의해 자동으로 생성됩니다. 초기 프로젝트 컨텍스트, 특히 **제품 컨텍스트 (Product Context)**의 부트스트랩 (bootstrap)을 돕기 위해 다음 사항을 고려하십시오:

생성: 프로젝트 워크스페이스의 루트 디렉토리에 projectBrief.md라는 이름의 파일을 생성하십시오.

내용 추가: 이 파일에 프로젝트에 대한 상위 수준의 개요를 작성하십시오. 여기에는 다음 내용이 포함될 수 있습니다:

• 프로젝트의 주요 목표 또는 목적.
• 핵심 기능 또는 구성 요소.
• 타겟 오디언스 (Target audience) 또는 사용자.
• 전반적인 아키텍처 스타일 또는 주요 기술 (알려진 경우).
• 프로젝트를 정의하는 기타 기초 정보.

가져오기를 위한 자동 프롬프트 (Automatic Prompt for Import): 제공된 ConPort 커스텀 인스트럭션 세트(예: roo_code_conport_strategy)를 사용하는 LLM 에이전트가 워크스페이스에서 초기화될 때, 다음과 같이 설계되었습니다:

• projectBrief.md의 존재 여부를 확인합니다.
• 파일이 발견되면, 해당 파일을 읽고 그 내용을 ConPort의 **제품 컨텍스트 (Product Context)**로 가져올지 사용자에게 묻습니다.
• 사용자가 동의하면, 해당 내용이 ConPort에 추가되어 프로젝트의 제품 컨텍스트를 위한 즉각적인 베이스라인 (baseline)을 제공합니다.

projectBrief.md를 찾을 수 없거나 가져오기를 선택하지 않은 경우:

• LLM 에이전트(커스텀 인스트럭션의 안내에 따라)는 일반적으로 ConPort 제품 컨텍스트가 초기화되지 않은 것으로 보인다고 사용자에게 알립니다.
• 워크스페이스의 다른 파일들을 나열하여 관련 정보를 수집하는 방식으로, 제품 컨텍스트를 수동으로 정의할 수 있도록 도움을 제안할 수 있습니다.

projectBrief.md를 통하거나 수동 입력을 통해 초기 컨텍스트를 제공함으로써, ConPort와 연결된 LLM 에이전트가 시작부터 프로젝트에 대한 더 나은 기초적 이해를 가질 수 있도록 할 수 있습니다.

ConPort는 올바른 workspace_id를 자동으로 결정할 수 있습니다.

따라서 MCP 클라이언트 설정에 절대 경로를 하드코딩할 필요가 없습니다. 이는 MCP 서버를 실행할 때 ${workspaceFolder}를 확장하지 못하는 IDE(통합 개발 환경)의 경우 특히 유용합니다.

탐지 기능은 기본적으로 활성화되어 있으며, CLI 플래그를 통해 제어할 수 있습니다:

플래그 (Flags):

--auto-detect-workspace (기본값: enabled) 자동 탐지를 활성화합니다.

--no-auto-detect 탐지를 비활성화합니다 (이 경우 명시적인 --workspace_id 또는 도구별 workspace_id를 반드시 제공해야 합니다).

--workspace-search-start <path> 상위 탐색을 위한 선택적 시작 디렉토리입니다 (기본값은 현재 작업 디렉토리입니다).

작동 방식 (다중 전략):

• 강력한 지표 (Strong Indicators, 빠른 경로): 다음 중 하나를 포함하는 신뢰도가 높은 프로젝트 루트를 찾습니다:
  package.json, .git, pyproject.toml, Cargo.toml, go.mod, pom.xml.

• 다중 일반 지표 (Multiple General Indicators): 디렉토리에 2개 이상의 일반 지표(README, 라이선스, 빌드 파일 등)가 존재하는 경우, 해당 디렉토리를 루트로 취급합니다.

• 기존 ConPort 워크스페이스: context_portal/ 디렉토리가 존재하는 경우