Project Guardian MCP

지속적인 프로젝트 메모리, 지식 그래프 작업, SQLite 데이터 액세스, 런타임 보안 검사, 그리고 안내형 프로젝트 관리 워크플로를 위한 MCP(Model Context Protocol) 서버입니다. 현재 레지스트리는 34개의 도구, 11개의 리소스, 27개의 프롬프트를 제공합니다.

목차

• 기능

  • Project Guardian 메모리 시스템

  • 간소화된 데이터베이스 작업

  • 런타임 컴패니언 통합

  • AI 안내 시스템

  • 고급 기능

  • 엔터프라이즈 기능

• 요구 사항

• 설치

• 사용 가능한 도구

  • 데이터베이스 작업(도구 7개)

  • 메모리 및 안내 도구(도구 11개)

  • 런타임 컴패니언 도구(도구 12개)

  • UI 도구(도구 4개)

• AI 안내 시스템

  • 사용 가능한 리소스

  • 사용 가능한 프롬프트

  • AI 모델이 안내를 사용하는 방법

• 사용 예시

  • Project Guardian 설정

  • 프로젝트 관리 워크플로

  • 데이터베이스 작업

• 구성

  • 선택적 런타임 서비스

  • Cursor IDE용

  • Claude Desktop용

• 프로젝트 구조

• 개발

• 라이선스

Related MCP server: Engram

기능

Project Guardian 메모리 시스템

• 지식 그래프: 프로젝트 엔티티, 관계, 관찰 내용을 유지합니다

• 엔티티 관리: 풍부한 메타데이터를 가진 프로젝트, 작업, 사람, 리소스

• 관계 매핑: 의존성, 소유권, 차단 항목, 연결 관계

• 관찰 추적: 상황별 메모와 진행 상황 업데이트

• 시맨틱 검색: 엔티티 이름, 유형, 관찰 내용 전반에 걸친 SQLite 네이티브 FTS5 확장(MATCH 및 bm25() 랭킹)을 통한 빠른 로컬 RAG 매칭

• 프로젝트별 메모리: 각 프로젝트는 자체 memory.db를 가집니다. 서버는 다음 순서로 프로젝트 루트를 결정합니다: GUARDIAN_PROJECT_ROOT 환경 변수, 그다음 작업 디렉터리의 Git 최상위 디렉터리, 그다음 Git 저장소 외부의 공유 폴백으로 $XDG_DATA_HOME/project-guardian

• 중앙 메모리 미러: 모든 메모리 쓰기는 ~/memory/memory.db의 중앙 데이터베이스 하나에도 동기화되어, 모든 프로젝트에 걸친 통합 검색 가능 맵과 프로젝트 데이터베이스를 사용할 수 없을 때의 폴백을 제공합니다. read_graph 및 search_nodes를 통한 읽기는 두 저장소를 병합하며, 프로젝트 항목이 우선합니다

• 일일 중앙 백업: 매일 첫 동기화 시 중앙 데이터베이스가 ~/memory/backup/ddmmyyyy_memory.db로 스냅샷됩니다. 가장 최근 백업 7개가 유지되고 오래된 백업은 자동으로 정리됩니다. 첫 실행 시 홈 디렉터리의 레거시 ~/memory.db가 새 레이아웃으로 마이그레이션되어 첫 백업을 시드하는 데 사용됩니다

• 온디맨드 Pre-Commit 설정: 시작 시 아무것도 설치되지 않습니다. 활성 프로젝트에서 생성된 .pre-commit-config.yaml과 Git 훅을 원할 때 setup_pre_commit을 호출하세요

• 온디맨드 웹 UI: start_ui(포트를 해제하려면 close_ui/stop_ui)를 통해 터미널 테마의 대화형 노드 그래프를 실행하여 프로젝트 상태를 시각적으로 이동, 검색, 탐색할 수 있습니다. 모바일 게이트(<768px 오버레이)가 있는 데스크톱 전용, 항상 표시되는 엔티티 브라우저, 클러스터형 앰버 오브 → 관찰별 시안으로 확장, 커서 스트리밍 GET /api/graph/stream?cursor=&limit=500 + react-window 가상 목록, >1k 물리 동결.

간소화된 데이터베이스 작업

• 두 저장소, 하나의 인터페이스: 모든 프로젝트는 자체 memory.db를 사용합니다. 7개의 데이터베이스 도구 모두 database: "central"로 중앙 집계 저장소를 대상으로 지정할 수도 있습니다

• 핵심 CRUD: 필수 데이터베이스 작업(쿼리, 삽입, 업데이트, 삭제)

• SQL 실행: 직접 SQL 쿼리 실행

• 데이터 전송: CSV 및 JSON 파일 가져오기/내보내기

• 총 34개 도구: 데이터베이스 도구 7개, 메모리 도구 10개, 안내 도구 1개, 런타임 컴패니언 도구 12개, UI/스트림 도구 4개(start_ui, close_ui, stop_ui, read_graph_stream)

런타임 컴패니언 통합

이 저장소에는 6개의 guardian-* AgentSkills가 포함되어 있으며, 해당 운영 기능을 타입이 지정된 MCP 도구로 노출합니다:

AgentSkills는 호스트 측 워크플로와 지침을 제공합니다. MCP 런타임은 컨테이너 스캔을 제외하고 해당 작업을 TypeScript로 직접 구현하며, 컨테이너 스캔은 Trivy를 제한된 외부 프로세스로 호출합니다. 일반적인 스크립트 또는 셸 실행 도구는 노출되지 않습니다.

AI 안내 시스템

• 리소스 11개: 템플릿, 모범 사례, 프로젝트 상태, 컴패니언 기능 상태

• 프롬프트 27개: 프로젝트 관리의 모든 측면을 위한 포괄적인 사전 구축 워크플로

• 전문가 안내: 복잡한 작업을 위한 단계별 지침

• 상황별 도움말: 사용자 요구에 기반한 적응형 프롬프트

• 지식 베이스: 포괄적인 프로젝트 관리 지식

고급 기능

• 스키마 검증: Zod 스키마를 통한 포괄적인 입력 검증

• 오류 처리: 상세한 오류 메시지와 우아한 실패 처리

• 연결 관리: WAL + synchronous=NORMAL + cache_size=-64000 + journal_size_limit=67108864 + temp_store=MEMORY + busy_timeout=5000이 적용된 20개 연결로 제한된 LRU 캐시, 월간 VACUUM(POST /api/vacuum) 및 종료 시 정리

• 파일 통합: CSV 및 SQL 가져오기는 스트리밍됩니다. CSV 쓰기는 제한된 문자열 조립을 사용합니다

• 결과 제한 및 페이지네이션: 무제한 원시 SELECT는 10,000행으로 제한됩니다. read_graph/readStore는 ?limit=&offset=와 함께 기본 5000, read_graph_stream은 GET /api/graph/stream?cursor=&limit=& + POST /api/vacuum을 통한 커서 500/page, search_nodes는 100개로 제한(하이브리드 RRF k=60)

엔터프라이즈 기능

• TypeScript: 포괄적인 오류 처리를 갖춘 완전한 타입 지정

• 입력 검증: 모든 매개변수에 대한 Zod 스키마 검증

• 오류 복구: 상세한 오류 메시지와 함께 우아한 오류 처리

• 리소스 관리: 연결 및 리소스 자동 정리

• 테스트: 93개의 통과 테스트가 있는 10개의 Jest 스위트(WAL + 페이지네이션 + close_ui + read_graph_stream + e2e-vector hybrid)

요구 사항

• Node.js: >= 18.0.0

• npm: 최신 안정 버전

• SQLite3: 종속성으로 자동 설치됨

• Redis: 선택 사항. REDIS_URL을 통한 cache_* 도구에만 필요

• Trivy: 선택 사항. scan_container_image에만 필요

설치

1. 저장소를 클론합니다:

git clone https://github.com/1999AZZAR/project-guardian-mcp-server.git
cd project-guardian-mcp-server

2. 종속성을 설치합니다:

npm install

3. 프로젝트를 빌드합니다: 개발 빌드 또는 프로덕션 빌드 중에서 선택하세요:

개발용(소스 맵 및 전체 TypeScript 컴파일 포함):

npm run build

프로덕션용(최적화되고 축소된 번들 생성):

npm run build:prod

4. 테스트 스위트를 실행합니다:

npm test

5. 서버를 시작합니다:

npm start

변경 후 업데이트

새 업데이트를 가져오거나 코드를 수정한 경우, 변경 사항을 적용하려면 서버를 다시 빌드하고 MCP 클라이언트(Cursor, Claude Desktop 등)를 다시 시작해야 합니다:

1. 최신 코드를 가져옵니다: git pull

2. 새 종속성을 설치합니다(있는 경우): npm install

3. 번들을 다시 빌드합니다: npm run build:prod

4. 중요: IDE 또는 MCP 연결을 다시 시작하여 클라이언트가 새로 업데이트된 도구와 프롬프트를 가져올 수 있게 하세요.

사용 가능한 도구

이 MCP 서버는 현재 34개의 도구를 제공합니다:

데이터베이스 작업(도구 7개)

모든 데이터베이스 도구는 선택적 database 선택자를 허용합니다: project(기본값)는 활성 프로젝트의 memory.db를 대상으로 하고, central은 ~/memory/memory.db의 중앙 집계 저장소를 대상으로 합니다.

execute_sql - SQL 쿼리 실행

선택한 메모리 데이터베이스에서 원시 SQL 쿼리를 실행합니다.

매개변수:

• query (필수): SQL 쿼리 문자열

• parameters (선택): 쿼리 매개변수 배열

• database (선택): "project" 또는 "central", 기본값 "project"

query_data - 테이블 데이터 쿼리

필터링 및 페이지네이션으로 메모리 테이블을 쿼리합니다.

매개변수:

• table (필수): 테이블 이름

• conditions (선택): WHERE 조건 객체

• limit (선택): 반환할 최대 행 수

• offset (선택): 건너뛸 행 수

• orderBy (선택): 정렬 기준 열

• orderDirection (선택): 정렬 방향("ASC" 또는 "DESC")

• database (선택): "project" 또는 "central", 기본값 "project"

insert_data - 레코드 삽입

메모리 테이블에 레코드를 삽입합니다.

매개변수:

• table (필수): 테이블 이름

• records (필수): 삽입할 레코드 객체 배열

• database (선택): "project" 또는 "central", 기본값 "project"

update_data - 레코드 업데이트

메모리 테이블의 레코드를 업데이트합니다.

매개변수:

• table (필수): 테이블 이름

• conditions (필수): 업데이트할 레코드의 WHERE 조건

• updates (필수): 업데이트할 필드

• database (선택): "project" 또는 "central", 기본값 "project"

delete_data - 레코드 삭제

메모리 테이블에서 레코드를 삭제합니다.

매개변수:

• table (필수): 테이블 이름

• conditions (필수): 삭제할 레코드의 WHERE 조건

• database (선택): "project" 또는 "central", 기본값 "project"

import_data - 데이터 가져오기

CSV 또는 JSON 파일에서 메모리 테이블로 데이터를 가져옵니다.

매개변수:

• table (필수): 대상 테이블 이름

• filePath (필수): 소스 파일 경로

• format (선택): 파일 형식("csv" 또는 "json")

• options (선택): 가져오기 옵션(delimiter, hasHeader)

• database (선택): "project" 또는 "central", 기본값 "project"

export_data - 데이터 내보내기

메모리 테이블 데이터를 CSV 또는 JSON 파일로 내보냅니다.

매개변수:

• table (필수): 원본 테이블 이름

• filePath (필수): 출력 파일 경로

• format (선택): 출력 형식 ("csv" 또는 "json")

• conditions (선택): 내보내기를 필터링할 WHERE 조건

• options (선택): 내보내기 옵션 (delimiter, includeHeader)

• database (선택): "project" 또는 "central", 기본값 "project"

메모리 및 가이던스 도구 (11개 도구)

initialize_memory - 메모리 시스템 초기화

프로젝트 메모리 데이터베이스 스키마와 테이블을 설정합니다.

매개변수: 없음

create_entity - 프로젝트 엔티티 생성

프로젝트 지식 그래프에 엔티티를 생성합니다 (단일 또는 일괄 지원).

매개변수:

• entities (필수): 엔티티 객체 배열

  • name: 엔티티 이름

  • entityType: 유형 (project, task, person, resource)

  • observations: 엔티티에 대한 메모 배열

create_relation - 엔티티 관계 생성

프로젝트 엔티티 간의 관계를 생성합니다 (단일 또는 일괄 지원).

매개변수:

• relations (필수): 관계 객체 배열

  • from: 소스 엔티티 이름

  • to: 대상 엔티티 이름

  • relationType: 관계 유형 (depends_on, blocks, owns 등)

add_observation - 엔티티 관찰 항목 추가

프로젝트 엔티티에 관찰 항목/메모를 추가합니다 (단일 또는 일괄 지원).

매개변수:

• observations (필수): 관찰 객체 배열

  • entityName: 대상 엔티티 이름

  • contents: 추가할 관찰 문자열 배열

delete_entity - 프로젝트 엔티티 삭제

프로젝트 메모리에서 엔티티와 해당 관계를 제거합니다 (단일 또는 일괄 지원).

매개변수:

• entityNames (필수): 삭제할 엔티티 이름 배열

delete_observation - 엔티티 관찰 항목 제거

엔티티에서 특정 관찰 항목을 제거합니다 (단일 또는 일괄 지원).

매개변수:

• deletions (필수): 삭제 객체 배열

  • entityName: 대상 엔티티 이름

  • observations: 제거할 관찰 문자열 배열

delete_relation - 엔티티 관계 삭제

프로젝트 엔티티 간의 관계를 제거합니다 (단일 또는 일괄 지원).

매개변수:

• relations (필수): 삭제할 관계 객체 배열

  • from: 소스 엔티티 이름

  • to: 대상 엔티티 이름

  • relationType: 삭제할 관계 유형

read_graph - 프로젝트 지식 그래프 읽기

활성 프로젝트 데이터베이스와 중앙 집계를 병합하여 전체 지식 그래프를 검색합니다. 같은 이름의 엔티티는 중앙 항목보다 프로젝트 항목이 우선합니다. 페이지네이션을 지원합니다.

매개변수:

• database (선택): "project" (기본값, 병합됨), "central" (중앙만)

• limit (선택, 1-10000, 기본값 5000): 반환할 최대 엔티티/관계 수, ORDER BY updated_at DESC

• offset (선택, 0 이상): 건너뛸 행 수

search_nodes - 프로젝트 지식 검색

프로젝트 데이터베이스와 중앙 집계 모두에서 이름, 유형, 콘텐츠를 대상으로 쿼리와 일치하는 엔티티와 관계를 검색합니다. FTS5 MATCH + bm25() 순위를 사용합니다.

매개변수:

• query (필수): 검색어

• limit (선택, 1-100, 기본값 20): 반환할 최대 순위 엔티티 수

open_node - 엔티티 세부 정보 가져오기

프로젝트 엔티티에 대한 자세한 정보를 검색합니다 (단일 또는 일괄 지원).

매개변수:

• names (필수): 검색할 엔티티 이름 배열

get_project_guidance - AI 가이던스 접근

프로젝트 가이던스 프레임워크를 호출하여 특정 워크플로에 대한 전문 지침과 체크리스트를 받습니다. 이를 통해 AI는 확립된 프로젝트 관리 프로토콜을 자율적으로 가져와 따를 수 있습니다.

매개변수:

• guidance_name (필수): 가이던스 이름 (예: project-setup, sprint-planning)

• arguments (선택): 특정 가이던스 프레임워크에 필요한 인수

런타임 컴패니언 도구 (12개 도구)

sync_central_memory

활성 프로젝트 지식 그래프를 중앙 메모리 데이터베이스(기본값 ~/memory/memory.db, GUARDIAN_CENTRAL_DB로 재정의)에 복사합니다. 엔티티는 업서트되고 관계는 중복 제거되므로, 중앙 데이터베이스는 모든 프로젝트에 걸쳐 검색 가능한 맵을 축적합니다. 모든 메모리 쓰기도 자동으로 동기화됩니다. 필요 시 이 도구를 호출하여 강제로 동기화할 수 있습니다. 매일 첫 동기화 시 중앙 데이터베이스의 스냅샷을 생성하고 최신 7개를 제외한 오래된 백업을 정리합니다.

set_project_root

활성 프로젝트 메모리 데이터베이스를 지정된 절대 프로젝트 경로로 전환합니다. 서버가 프로젝트 디렉터리 밖에서 시작된 경우 세션 시작 시 이 도구를 사용하여 공유 폴백 데이터베이스 대신 프로젝트에 메모리가 기록되도록 합니다.

• path (필수): 프로젝트 루트의 절대 경로. Git 저장소 내부에서는 최상위 디렉터리(toplevel)가 사용됩니다.

setup_pre_commit

요청 시 활성 프로젝트 루트에 .pre-commit-config.yaml을 생성하고 Git 훅을 설치합니다. pre-commit이 설치되어 있어야 합니다. 생성되는 .gitignore 항목은 의도적으로 광범위합니다. memory.db와 함께 해당 블록은 .claude/, .vscode/, .idea/, .gemini/, .cursor/ 같은 일반적인 로컬 도구 디렉터리와 .env 파일을 무시합니다. .gitignore에 이미 있는 항목은 절대 중복되지 않습니다. 서버는 시작 시 이러한 작업을 자동으로 수행하지 않습니다.

get_session_context

지식 그래프에서 직접 활성 작업, 열린 버그, 최근 변경 사항, 차단 요인, 다음 권장 작업을 요약합니다.

• limit (선택, 1-50, 기본값 10): 결과 그룹당 최대 항목 수.

analyze_git_changes

Git에서 이름 변경(rename)과 선택적으로 추적되지 않은 파일을 포함한 정확한 기계 판독 가능 변경 경로를 반환합니다.

• commit (선택): 하나의 커밋을 부모 커밋과 비교하여 분석합니다.

• since (선택, 기본값 1): N개 커밋 이전 또는 Git 날짜 이후의 변경 사항을 분석합니다.

• includeUntracked (선택, 기본값 true): 작업 트리 분석에 추적되지 않은 파일을 포함합니다.

• maxFiles (선택, 1-500, 기본값 100): 반환되는 경로 수를 제한합니다.

• commit과 사용자 지정 since 값은 함께 사용할 수 없습니다.

inspect_untrusted_text

최대 256 KiB의 신뢰할 수 없는 텍스트를 정규화하고 숨겨진 서식, 명령어 재정의, 역할 모방, 숨겨진 HTML/CSS, 원격 유출 마크업, 인코딩된 명령어 유사 콘텐츠를 감지합니다.

• text (필수): 외부 또는 기타 신뢰할 수 없는 콘텐츠.

• 감지는 휴리스틱입니다. 반환된 정규화 텍스트는 여전히 신뢰할 수 없는 데이터입니다.

scan_project_secrets

워크스페이스 기준 파일 또는 디렉터리에서 하드코딩된 자격 증명으로 보이는 항목을 스캔합니다. 결과에는 유형, 상대 파일 경로, 줄 번호만 포함되며 일치된 값은 절대 반환되지 않습니다.

• path (선택, 기본값 .): 워크스페이스 기준 스캔 대상.

• exclude (선택): 건너뛸 추가 디렉터리 이름.

• maxFindings (선택, 1-500, 기본값 100): 발견 항목 수를 제한합니다.

• 절대 경로, 경로 이탈(traversal), 존재하지 않는 경로, 심볼릭 링크 이탈은 거부됩니다.

scan_container_image

시간 제한이 있는 Trivy 스캔을 실행하고 제한된 HIGH/CRITICAL 취약점 요약을 반환합니다.

• image (필수): 컨테이너 이미지 참조.

• maxFindings (선택, 1-500, 기본값 100): 발견 항목 수를 제한합니다.

• Trivy가 필요합니다. -로 시작하거나, 공백을 포함하거나, 제어 문자를 포함하는 이미지 값은 거부됩니다.

Redis 캐시 도구

• cache_get: mema:<category>:<name> 키 하나를 읽습니다.

• cache_set: 최대 512 KiB의 값을 선택적 ttlSeconds(1~604800)와 함께 저장합니다.

• cache_delete: 네임스페이스가 지정된 키 하나를 삭제합니다.

• cache_scan: 제한된 개수로 mema:* 패턴을 커서 스캔합니다.

프로젝트 스캔 경로는 현재 Git 워크스페이스로 제한됩니다. Redis 도구는 지연 연결되며 REDIS_URL이 설정되지 않은 경우 사용 불가 오류를 반환합니다. 컨테이너 스캔은 Trivy가 설치될 때까지 사용할 수 없습니다. 현재 기능 상태는 project-guardian://companions/catalog에서 확인하세요.

UI 도구 (4개 도구)

start_ui

주문형 Project Guardian Web UI 서버를 시작하여 브라우저에서 지식 그래프를 시각적으로 탐색할 수 있게 합니다. 사용 가능한 포트를 자동으로 찾아(기본값 3000, 충돌 시 3001… 시도) 로컬 HTTP URL을 반환합니다. UI는 ui/dist에서 CRT 테마의 포스 그래프를 제공하며 올바른 정적 경로 폴백(ui/dist → MCPservers/.../ui/dist)을 사용합니다.

• 매개변수: 없음

• 반환값: UI Server successfully started on http://localhost:<port>

• 기능: 데스크톱 전용(<768px에서 모바일 게이트), 엔티티 브라우저 항상 표시, 관찰 오브(클러스터된 앰버 → 확장 시 시안), /api/graph/*에서 페이지네이션된 ?limit=&offset=.

close_ui / stop_ui

실행 중인 Web UI 서버를 중지하고 포트를 해제합니다.

• 매개변수: 없음

• 반환값: UI Server stopped

• stop_ui는 close_ui의 별칭입니다.

AI 가이던스 시스템

Project Guardian MCP는 AI 모델이 프로젝트 관리를 위해 도구 세트를 효과적으로 사용할 수 있도록 포괄적인 리소스와 프롬프트를 포함합니다.

사용 가능한 리소스

Project Guardian은 AI 모델이 프로젝트 관리 개념을 이해하고, 기능 상태를 확인하고, 포괄적인 프로젝트 인사이트를 얻기 위해 읽을 수 있는 11가지 핵심 리소스를 제공합니다:

project-guardian://templates/entity-types

예시와 사용 지침이 포함된 프로젝트 관리 표준 엔티티 유형.

project-guardian://templates/relationship-types

실용적인 예시가 포함된 프로젝트 엔티티 간의 일반적인 관계 유형.

project-guardian://templates/project-workflows

다양한 시나리오에서 Project Guardian 도구를 사용하기 위한 표준 워크플로.

project-guardian://templates/best-practices

효과적인 프로젝트 지식 관리를 위한 종합 모범 사례 가이드.

project-guardian://status/current-graph

요약 통계가 포함된 프로젝트 지식 그래프의 현재 상태.

project-guardian://cache/recent-activities

진행 상황 추적을 위해 최근 수행된 프로젝트 관리 활동 및 업데이트.

project-guardian://cache/workflow-templates

예시와 구현 지침이 포함된 자주 사용되는 워크플로 템플릿.

project-guardian://metrics/project-stats

건강 지표가 포함된 프로젝트 엔티티, 관계, 활동의 통계 개요.

project-guardian://cache/team-members

프로젝트 팀 구성원과 조직 내 역할에 대한 캐시된 정보.

project-guardian://status/recent-changes

감사 및 모니터링을 위한 지식 그래프의 최근 추가, 업데이트, 수정 사항.

project-guardian://companions/catalog

6개 컴패니언 전체, 해당 MCP 도구, 외부 전제 조건, 현재 사용 가능 여부를 나열합니다.

사용 가능한 프롬프트

Project Guardian은 프로젝트 설정, 계획, 품질, 운영, 인시던트 워크플로를 다루는 27개 프롬프트를 제공합니다:

핵심 프로젝트 관리

project-setup - 프로젝트 초기화

인수:

• project_name (필수): 프로젝트 이름

• team_members (선택): 쉼표로 구분된 팀 구성원 목록

적절한 엔티티와 관계로 새 프로젝트 구조를 설정하기 위한 단계별 지침을 제공합니다.

sprint-planning - 스프린트 계획

인수:

• sprint_name (필수): 스프린트 이름/번호

• duration_days (선택): 스프린트 기간(일)

작업 분해, 종속성, 용량 계획을 포함한 포괄적인 스프린트 계획을 안내합니다.

progress-update - 진행 상황 추적

인수:

• task_name (필수): 업데이트할 작업 이름

• progress_notes (필수): 진행 상황 업데이트 설명

작업 진행 상황을 업데이트하고 종속성을 관리하기 위한 구조화된 프로세스.

retrospective - 프로젝트 회고

인수:

• time_period (필수): 검토 중인 기간 (예: "last sprint", "Q1")

데이터 분석, 패턴 식별, 개선 조치 생성을 포함한 포괄적인 회고 프로세스.

품질 및 프로세스 관리

code-review - 코드 리뷰 프로세스

인수:

• pull_request_title (필수): 검토 중인 풀 리퀘스트의 제목

• reviewer_name (선택): 리뷰어 이름

기술 체크리스트, 이슈 문서화, 승인 워크플로를 포함한 구조화된 코드 리뷰 프로세스.

bug-tracking - 버그 관리

인수:

• bug_description (필수): 버그 또는 문제에 대한 설명

• severity_level (선택): 치명적, 높음, 중간, 낮음 심각도

발견부터 해결까지의 완전한 버그 추적 워크플로우와 영향 분석 및 이해관계자 커뮤니케이션.

technical-debt-assessment - 기술 부채 분석

인자:

• component_name (필수): 평가 대상 구성 요소 또는 코드베이스의 이름

• assessment_scope (선택): 평가 범위 (파일, 모듈, 시스템)

포괄적인 기술 부채 식별, 우선순위 지정, 그리고 개선 계획 수립.

릴리스 및 배포 관리

release-planning - 릴리스 계획

인자:

• release_version (필수): 릴리스 버전 번호 (예: "v2.1.0")

• release_date (선택): 목표 릴리스 날짜

품질 게이트, 위험 평가, 배포 조정을 포함한 완전한 릴리스 계획 프로세스.

위험 및 변경 관리

risk-assessment - 위험 관리

인자:

• risk_description (필수): 위험에 대한 설명

• impact_level (선택): 높음, 중간, 낮음 영향도

위험 문서화, 영향 식별, 완화 전략 개발을 위한 완전한 워크플로우.

change-management - 변경 통제

인자:

• change_description (필수): 제안된 변경 사항에 대한 설명

• impact_assessment (선택): 높음, 중간, 낮음 영향 평가

영향 분석, 승인 워크플로우, 구현 추적을 포함한 구조화된 변경 관리 프로세스.

팀 및 자원 관리

team-productivity - 생산성 분석

인자:

• timeframe (필수): 분석할 기간 (주, 월, 분기)

• focus_area (선택): 집중 영역 (속도, 품질, 협업)

성과 지표, 근본 원인 분석, 개선 계획을 포함한 팀 생산성 평가.

resource-allocation - 자원 계획

인자:

• resource_type (필수): 자원 유형 (인력, 인프라, 예산)

• planning_horizon (선택): 계획 기간 (스프린트, 분기, 연도)

용량 계획, 격차 분석, 활용도 추적을 포함한 자원 할당 최적화.

문서화 및 커뮤니케이션

stakeholder-communication - 커뮤니케이션 관리

인자:

• communication_type (필수): 커뮤니케이션 유형 (status_update, issue_alert, milestone_reached)

• audience (선택): 대상 청중 (팀, 경영진, 고객, 전체)

대상별 전략과 효과 추적을 포함한 이해관계자 커뮤니케이션 계획 및 실행.

documentation-management - 문서 업데이트

인자:

• documentation_type (필수): 문서 유형 (api, user_guide, technical_spec)

• update_reason (선택): 문서 업데이트 사유

콘텐츠 계획, 검토 워크플로우, 게시 조정을 포함한 문서 유지 관리 프로세스.

요구사항 및 계획 관리

requirements-gathering - 요구사항 수집

인자:

• requirement_type (필수): 요구사항 유형 (기능적, 비기능적, 비즈니스, 기술적)

• stakeholders (선택): 주요 이해관계자 목록 (쉼표로 구분)

이해관계자 관리와 요구사항 분류를 포함한 포괄적인 요구사항 수집 프로세스 안내.

user-story-management - 사용자 스토리 관리

인자:

• feature_name (필수): 기능 또는 에픽의 이름

• user_role (선택): 주요 사용자 역할 (예: "고객", "관리자", "개발자")

수락 기준과 의존성을 포함한 사용자 스토리 생성, 관리, 우선순위 지정을 위한 구조화된 프로세스.

품질 및 기술 관리

testing-strategy - 테스트 전략 개발

인자:

• application_type (필수): 애플리케이션 유형 (웹, 모바일, API, 데스크톱)

• criticality_level (선택): 비즈니스 중요도 (치명적, 높음, 중간, 낮음)

자동화 테스트, 품질 게이트, 위험 기반 테스트를 포함한 포괄적인 테스트 전략 개발.

security-assessment - 보안 평가

인자:

• assessment_scope (필수): 보안 평가 범위 (애플리케이션, 인프라, 데이터)

• compliance_requirements (선택): 규정 준수 표준 (GDPR, HIPAA, SOC2 등)

취약점 관리, 규정 준수 검증, 보안 통제 구현을 포함한 보안 평가 프레임워크.

performance-optimization - 성능 최적화

인자:

• performance_metric (필수): 최적화할 주요 지표 (response_time, throughput, resource_usage)

• optimization_goal (선택): 특정 성능 목표 또는 개선 비율

성능 모니터링 설정, 병목 지점 식별, 지속적인 모니터링을 통한 최적화 구현.

ci-cd-setup - CI/CD 파이프라인 설정

인자:

• pipeline_type (필수): 파이프라인 유형 (build, test, deploy, full_ci_cd)

• target_platform (선택): 배포 대상 (aws, azure, gcp, kubernetes, heroku)

품질 게이트, 롤백 절차, 보안 통합을 포함한 완전한 CI/CD 파이프라인 설정.

architecture-review - 아키텍처 검토

인자:

• architecture_type (필수): 아키텍처 유형 (마이크로서비스, 모놀리식, 서버리스, 하이브리드)

• review_focus (선택): 주요 초점 영역 (확장성, 보안, 유지보수성, 성능)

설계 패턴 분석, 기술 스택 평가, 개선 권장 사항을 포함한 아키텍처 평가 프레임워크.

지식 및 팀 관리

knowledge-transfer - 지식 전수

인자:

• knowledge_domain (필수): 지식 영역 (기술, 프로세스, 비즈니스)

• transfer_recipients (선택): 지식을 받을 대상 (팀, 개인, 부서)

세션 관리, 문서화, 효과 검증을 포함한 지식 전수 계획 및 실행.

vendor-management - 공급업체 관리

인자:

• vendor_type (필수): 공급업체 서비스 유형 (클라우드, 개발, 컨설팅, 인프라)

• contract_value (선택): 계약 금액 범위 (소규모, 중간, 대규모, 엔터프라이즈)

계약 추적, 성과 모니터링, 비용 최적화를 포함한 공급업체 관계 관리.

사고 및 위기 관리

incident-response - 사고 대응

인자:

• incident_severity (필수): 심각도 수준 (치명적, 높음, 중간, 낮음)

• incident_type (선택): 사고 유형 (보안, 성능, 기능, 가용성)

차단, 복구, 근본 원인 분석, 사후 검토를 포함한 사고 대응 프레임워크.

재무 및 자원 관리

cost-management - 비용 관리

인자:

• cost_category (필수): 주요 비용 범주 (인프라, 인력, 도구, 라이선스)

• budget_constraint (선택): 예산 제약 수준 (엄격, 유연, 무제한)

비용 모니터링, 최적화 전략, 예측 및 보고를 포함한 예산 관리.

고객 및 혁신 관리

customer-feedback - 고객 피드백 관리

인자:

• feedback_channel (필수): 주요 피드백 채널 (설문, 지원, 리뷰, 분석)

• feedback_focus (선택): 초점 영역 (사용성, 기능, 성능, 지원)

지속적인 개선 주기를 포함한 고객 피드백 수집, 분석, 실행 계획 수립.

innovation-planning - 혁신 계획

인자:

• innovation_type (필수): 혁신 유형 (제품, 프로세스, 기술, 비즈니스 모델)

• risk_tolerance (선택): 위험 허용 수준 (보수적, 중간, 공격적)

아이디어 생성, 실험, 성과 측정을 포함한 혁신 관리 프레임워크.

AI 모델이 가이드를 사용하는 방법

1. 발견: 사용 가능한 리소스와 프롬프트를 나열하여 기능을 이해합니다.

2. 학습: 관련 리소스를 읽고 프로젝트 관리 개념을 이해합니다.

3. 계획: 복잡한 워크플로우에 적절한 프롬프트를 사용합니다.

4. 실행: 구조화된 가이드를 따라 도구를 효과적으로 사용합니다.

5. 검증: 결과를 확인하고 필요에 따라 반복합니다. 이 가이드 시스템은 AI 모델이 Project Guardian 도구 세트를 사용하여 전문가 수준의 프로젝트 관리 지원을 제공할 수 있도록 보장합니다.

행동 프로토콜 (시스템 규칙)

이 MCP 서버의 모든 prompts/get 응답에는 공유 행동 프로토콜이 시스템 메시지로 포함됩니다 (src/prompts/behavioral-protocol.ts에 구현됨). 이 프로토콜은 다음을 강제합니다:

• 최소한의 프로덕션 준비가 된 자체 문서화 코드와 보안 우선 접근 방식.

• 과장된 표현, 불필요한 이모지, 또는 채우기 없이 직접적이고 기술적으로 정확한 답변.

• 사용자 요청에 따른 적응형 응답 깊이 (빠른 답변 vs. 복잡한 분석).

• 시스템, 프로그래밍, UI/UX, 디자인에 대한 검증된 모범 사례의 일관된 사용.

이 MCP 서버를 통합하는 클라이언트는 첫 번째 시스템 메시지를 이러한 프롬프트를 사용하는 모든 다운스트림 모델에 대한 지배 규칙으로 취급해야 합니다.

사용 예시

Project Guardian 설정

// Initialize the project memory system
const initResult = await mcpClient.callTool('initialize_memory', {});

// Create your first project entities
const entityResult = await mcpClient.callTool('create_entity', {
  entities: [
    {
      name: 'web_platform',
      entityType: 'project',
      observations: ['Main web application platform', 'React + Node.js stack', 'Q2 2024 delivery']
    },
    {
      name: 'user_authentication',
      entityType: 'feature',
      observations: ['OAuth2 implementation', 'Google/GitHub providers', 'JWT tokens']
    }
  ]
});

// Establish project relationships
const relationResult = await mcpClient.callTool('create_relation', {
  relations: [
    {
      from: 'user_authentication',
      to: 'web_platform',
      relationType: 'part_of'
    }
  ]
});

프로젝트 관리 워크플로우

// Add progress observations
await mcpClient.callTool('add_observation', {
  observations: [
    {
      entityName: 'user_authentication',
      contents: [
        'Completed OAuth2 setup for Google provider',
        'JWT implementation finished',
        'Unit tests passing at 95% coverage'
      ]
    }
  ]
});

// Search project knowledge
const searchResult = await mcpClient.callTool('search_nodes', {
  query: 'authentication'
});

// Read entire project knowledge graph
const graphResult = await mcpClient.callTool('read_graph', {});

// Get detailed entity information
const entityDetails = await mcpClient.callTool('open_node', {
  names: ['user_authentication', 'web_platform']
});

데이터베이스 작업

// Execute custom SQL queries
const sqlResult = await mcpClient.callTool('execute_sql', {
  query: 'SELECT * FROM entities WHERE entity_type = ?',
  parameters: ['project']
});

// Query project data
const queryResult = await mcpClient.callTool('query_data', {
  table: 'entities',
  conditions: { entity_type: 'task' },
  limit: 10
});

// Import/export data
const importResult = await mcpClient.callTool('import_data', {
  table: 'project_data',
  filePath: './project_backup.csv',
  format: 'csv'
});

구성

환경 변수

서버는 시작 시 다음 변수를 읽습니다:

MCP 클라이언트는 자체 작업 디렉토리로 서버를 시작하며, 이는 종종 편집 중인 프로젝트가 아닌 홈 폴더입니다. 이 경우 Git 감지가 프로젝트를 찾을 수 없으며 모든 세션이 공유 대체 데이터베이스에 기록됩니다. 이 문제를 해결하는 두 가지 방법:

1. 프로젝트의 MCP 구성에 GUARDIAN_PROJECT_ROOT를 설정합니다 (아래 클라이언트 예시 참조).

2. 세션 시작 시 set_project_root 도구를 프로젝트의 절대 경로로 호출합니다 — 구성 편집이 필요 없습니다. 이 전환은 실행 중인 서버에 적용됩니다. 향후 모든 세션에 자동으로 적용하려면 환경 변수를 설정하십시오.

선택적 런타임 서비스

Redis는 선택 사항이며 시작 중에는 절대 연결되지 않습니다. 캐시 도구가 필요할 때만 구성하세요:

{
  "env": {
    "REDIS_URL": "redis://localhost:6379/0"
  }
}

Trivy는 scan_container_image가 호출될 때 PATH에서 검색됩니다. Redis나 Trivy가 없으면 관련 도구에만 영향을 미칩니다. memory, database, guidance, session, Git, wall 및 project-secret 도구는 계속 사용할 수 있습니다.

컴패니언 카탈로그는 각 런타임 기능에 대해 available, optional, unavailable을 보고합니다. 서버는 stdio 전송을 사용하며 HTTP 리스너를 노출하지 않습니다.

Cursor IDE용

이 서버를 Cursor MCP 구성(~/.cursor/mcp.json)에 추가하세요. GUARDIAN_PROJECT_ROOT 값을 이 구성이 속한 프로젝트로 바꾸세요:

{
  "mcpServers": {
    "project-guardian": {
      "command": "node",
      "args": ["/path/to/project-guardian-mcp-server/dist/index.js"],
      "env": {
        "GUARDIAN_PROJECT_ROOT": "/path/to/your/project"
      }
    }
  }
}

Claude Desktop용

이 서버를 동일한 패턴으로 Claude Desktop 구성(claude_desktop_config.json)에 추가하세요:

{
  "mcpServers": {
    "project-guardian": {
      "command": "node",
      "args": ["/path/to/project-guardian-mcp-server/dist/index.js"],
      "env": {
        "GUARDIAN_PROJECT_ROOT": "/path/to/your/project"
      }
    }
  }
}

프로젝트 구조

project-guardian-mcp-server/
├── src/
│   ├── index.ts              # Main entry point
│   ├── server.ts             # MCP server orchestrator
│   ├── memory-manager.ts     # Knowledge graph and FTS5 RAG semantic search
│   ├── sqlite-manager.ts     # Database operations and connection management
│   ├── import-export.ts      # CSV/JSON data import and export functionality
│   ├── ui-manager.ts         # On-Demand Web UI server and port finder
│   ├── types.ts              # TypeScript type definitions and schemas
│   ├── handlers/
│   │   └── request-handlers.ts # Central tool execution dispatcher
│   ├── tools/
│   │   ├── tool-registry.ts     # Tool definitions and listing
│   │   ├── database-tools.ts    # Database operation tool schemas
│   │   ├── memory-tools.ts      # Memory management tool schemas
│   │   ├── guidance-tools.ts    # Guidance tool schema
│   │   └── runtime-tools.ts     # Companion runtime tool schemas
│   ├── runtime/
│   │   ├── path-guard.ts        # Workspace path containment
│   │   └── runtime-capabilities.ts # Native companion implementations
│   ├── resources/
│   │   ├── resource-registry.ts  # Resource definitions and handlers
│   │   ├── resource-definitions.ts # Static resource metadata
│   │   ├── resource-handlers.ts   # Dynamic resource content generation
│   │   └── companion-catalog.ts   # Companion capability health
│   └── prompts/
│       ├── prompt-registry.ts       # Prompt definitions and handlers
│       ├── prompt-definitions.ts    # Static prompt metadata
│       ├── prompt-handlers.ts       # Dynamic prompt content generation
│       └── behavioral-protocol.ts   # Shared Behavioral Protocol system prompt
├── ui/                       # On-Demand Web UI frontend (Vite/React)
│   ├── src/
│   │   ├── App.tsx           # Main CRT-themed node graph visualization
│   │   ├── main.tsx          # React DOM entry point
│   │   └── index.css         # Styling, CRT scanlines, and CSS variables
│   └── vite.config.ts        # Vite build configuration
├── __tests__/                # Comprehensive test suite
│   ├── tool-registry.test.ts
│   ├── resource-registry.test.ts
│   ├── prompt-registry.test.ts
│   ├── request-handlers.test.ts
│   ├── runtime-capabilities.test.ts
│   ├── import-export.test.ts
│   ├── sqlite-manager.test.ts
│   └── bug-fixes.test.ts
├── skills/                   # Six distributable guardian-* AgentSkills
├── dist/                     # Ignored production build output
├── memory.db                 # Ignored local SQLite state, created on first run
├── package.json              # Project dependencies and scripts
├── package.prod.json         # Production-only dependencies for smaller bundle
├── tsconfig.json            # TypeScript configuration
├── jest.config.js           # Test configuration
└── README.md                # This documentation

주요 구성 요소

• server.ts: MCP 서버 수명 주기, 전송, 핸들러 및 종료 조정

• handlers/request-handlers.ts: 도구 호출을 적절한 관리자로 라우팅하는 중앙 디스패처

• tools/: 도구 정의 및 등록 시스템(총 34개 도구)

  • tool-registry.ts: 사용 가능한 모든 도구를 나열합니다(7 DB + 10 memory + 1 guidance + 12 runtime + 3 UI)

  • database-tools.ts: 데이터베이스 연산 스키마(7개 도구)

  • memory-tools.ts: 메모리 관리 스키마(10개 도구)

  • guidance-tools.ts: 자율 가이던스 도구 스키마(1개 도구)

  • runtime-tools.ts: 타입이 지정된 컴패니언 기능 스키마(12개 도구)

• runtime/: 작업 공간 가드 및 컴패니언 런타임 구현

• resources/: 리소스 관리 시스템(총 11개 리소스)

  • resource-registry.ts: 리소스 목록 및 콘텐츠 제공

  • resource-definitions.ts: 정적 리소스 메타데이터

  • resource-handlers.ts: 동적 콘텐츠 생성

• prompts/: 프롬프트 관리 시스템(총 27개 프롬프트)

  • prompt-registry.ts: 프롬프트 목록 및 콘텐츠 제공

  • prompt-definitions.ts: 정적 프롬프트 메타데이터

  • prompt-handlers.ts: 컨텍스트가 포함된 동적 프롬프트 생성

  • behavioral-protocol.ts: 모든 프롬프트에서 사용하는 중앙 집중식 Behavioral Protocol 시스템 메시지

• memory-manager.ts: 엔티티, 관계 및 관찰에 대한 지식 그래프 연산

• sqlite-manager.ts: 제한된 연결 캐싱 및 스키마 관리를 갖춘 데이터베이스 추상화

• import-export.ts: CSV, JSON 및 SQL 데이터 전송 유틸리티

• types.ts: 입력 검증 및 TypeScript 타입 안전성을 위한 Zod 스키마

• skills/: 6개 컴패니언 패키지를 위한 에이전트 측 워크플로, 스크립트, 참조 및 자산

로컬 상태

memory.db와 그 memory.db-* 사이드카 파일은 런타임 상태이며 Git에서 무시됩니다. 각 프로젝트는 결정된 프로젝트 루트에 자체 데이터베이스를 유지합니다(환경 변수 참조). 명시적 루트가 없는 Git 저장소 외부의 프로젝트는 $XDG_DATA_HOME/project-guardian 아래의 폴백 데이터베이스를 공유합니다. 또한 모든 메모리 쓰기는 ~/memory/memory.db의 중앙 데이터베이스에 미러링되며, 이는 프로젝트 간 병합입니다. 한 프로젝트에서 엔티티를 삭제해도 중앙 복사본에서는 제거되지 않으므로 중앙 데이터베이스를 프로젝트별 백업이 아닌 검색 가능한 집계로 취급하세요. 일일 스냅샷은 ~/memory/backup/에 저장됩니다. 클론은 프로젝트 메모리 없이 시작되며, 서버는 첫 실행 시 데이터베이스와 스키마를 로컬에 생성합니다. 머신 간에 이동해야 하는 경우 메모리를 명시적으로 백업하거나 내보내세요. 관찰에는 비공개 프로젝트 컨텍스트가 포함될 수 있으므로 데이터베이스를 커밋하지 마세요.

데이터베이스 도구(execute_sql, query_data, insert_data, update_data, delete_data, import_data, export_data)는 database 선택자를 허용합니다. project(기본값)는 활성 프로젝트 데이터베이스를 대상으로 하고, central은 집계를 대상으로 합니다.

개발

1. 저장소를 클론하세요:

git clone https://github.com/1999AZZAR/project-guardian-mcp-server.git
cd project-guardian-mcp-server

2. 의존성을 설치하세요:

npm install

3. 프로젝트를 빌드하세요: 활성 개발용(파일 감시 포함):

npm run dev

표준 빌드의 경우:

npm run build

프로덕션 최적화 빌드의 경우:

npm run build:prod

4. 테스트를 실행하세요:

npm test

5. 서버를 시작하세요:

npm start

라이선스

MIT 라이선스 - 자세한 내용은 LICENSE 파일을 참조하세요.