Auto Knowledge Sync MCP

LLM 개발 세션에서 얻은 기술 지식을 완결된 문서로 정리해, 개인 또는 팀의 지식 원천으로 축적하는 로컬 MCP 서버입니다. MCP는 사용자의 컴퓨터에서 Docker 컨테이너로 실행되고, 지식의 유일한 원본(SSOT)은 사용자가 지정한 private GitHub repository에 보관됩니다.

왜 필요한가요?

개발 중 LLM과 주고받은 설명·결정·주의사항은 유용하지만 세션이 끝나면 쉽게 사라집니다. 이 프로젝트는 다음 흐름을 평소의 MCP 사용 방식에 연결합니다.

1. LLM이 세션에서 재사용할 가치가 있는 기술 지식을 제안합니다.
2. MCP가 문서의 완결성, 개인정보·사내 민감정보, 원본 코드 포함 여부를 검사합니다.
3. 승인된 제안만 GitHub repository에 커밋합니다.
4. 이후 검색·검증·challenge·재구성을 통해 지식을 계속 갱신합니다.

저장되는 문서는 단순한 키워드 목록이 아니라 개념, 동작 방식, 기술적 의의, 해결하는 문제, 적용 조건과 한계를 설명하는 독립적인 knowledge entry입니다. 코드 예시가 필요하면 기존 업무 코드의 복사·변형이 아닌 새 예시만 허용합니다.

주요 특징

• 원격 SSOT: 지식과 변경 이력은 GitHub commit으로 남습니다. 로컬에는 재생성 가능한 검색 인덱스와 임시 데이터만 둡니다.
• 민감정보 차단: built-in secret·PII 검사와 선택적 조직별 deny rule을 적용하며, 검사 실패 시 저장하지 않는 fail-closed 정책을 사용합니다.
• 명시적 승인: 기본 승인 모드는 always입니다. 필요할 때만 on_risk 또는 never로 설정할 수 있으며, 보안 hard gate와 고위험 변경은 항상 검증됩니다.
• 지식 생명주기: 검색뿐 아니라 반례 제출, stale·중복 점검, 관계 정리, merge/split/reclassify/deprecate 제안을 지원합니다.
• 서버리스 운영: 상시 실행하는 중앙 서버나 운영 데이터베이스가 없습니다. MCP는 Codex, Claude Code 등 MCP 클라이언트가 필요할 때 로컬에서 실행합니다.
• 최소 권한: PAT는 지정한 private repository 하나에만 부여하고, MCP가 GitHub 조직·Actions·Pull request 권한을 요구하지 않습니다.

요구사항

• Docker Desktop 또는 Docker Engine
• 지식 저장소로 사용할 private GitHub repository
• 해당 repository만 선택한 fine-grained PAT
  • Metadata: Read-only
  • Contents: Read and write
  • Pull requests, Actions, Administration 권한은 부여하지 않음
• 소스에서 빌드할 경우 Node.js 24 이상과 Git

회사 자료를 저장하기 전 조직의 외부 GitHub 사용 정책을 확인하십시오. 첫 실행에서는 실제 업무 자료가 아닌 합성된 기술 내용으로 연결을 확인하는 것을 권장합니다.

빠른 시작

1. 소스와 로컬 이미지 준비

git clone https://github.com/One-armed-boy/auto-knowledge-sync-mcp.git
cd auto-knowledge-sync-mcp
npm ci
npm run build
docker build --tag auto-knowledge-sync-mcp:local .

2. PAT 파일과 설정 만들기

PAT를 shell command line이나 YAML에 직접 넣지 말고 owner-only 파일로 관리합니다.

CONFIG_DIR="$HOME/.config/auto-knowledge-sync"
PAT_FILE="$CONFIG_DIR/secrets/github_pat"

mkdir -p "$CONFIG_DIR/secrets"
umask 077
touch "$PAT_FILE"
chmod 600 "$PAT_FILE"
${EDITOR:-nano} "$PAT_FILE"

node dist/cli.js init \
  --repository <GITHUB_OWNER>/<PRIVATE_KNOWLEDGE_REPOSITORY> \
  --token-file "$PAT_FILE"

init은 기본 설정 파일을 만들고 repository에 knowledge manifest를 bootstrap합니다. 기본 설정을 그대로 사용하면 YAML을 직접 수정할 필요가 없습니다. 생성된 기본 경로는 다음과 같습니다.

$HOME/.config/auto-knowledge-sync/config.yaml
$HOME/.config/auto-knowledge-sync/secrets/github_pat

3. 연결 진단과 MCP 클라이언트 등록

doctor는 repository, PAT 권한, schema 호환성, branch와 cache 상태를 점검하고 Codex·Claude Code용 등록 명령을 출력합니다.

CONFIG_FILE="$CONFIG_DIR/config.yaml"

node dist/cli.js doctor \
  --config-file "$CONFIG_FILE" \
  --token-file "$PAT_FILE" \
  --client-commands \
  --image-ref auto-knowledge-sync-mcp:local \
  --host-config-file "$CONFIG_FILE" \
  --host-token-file "$PAT_FILE"

출력된 client_commands.codex 또는 client_commands.claude 명령을 해당 클라이언트에서 한 번 실행합니다. 등록 후에는 다음으로 연결을 확인할 수 있습니다.

codex mcp list
codex mcp get auto-knowledge-sync
claude mcp list
claude mcp get auto-knowledge-sync

이미지 대신 호스트의 빌드 결과를 직접 실행하는 client 명령이 필요하면 doctor --client-commands에서 --image-ref와 host mount 옵션을 생략하십시오. 안정적인 release image와 digest 고정 Compose runtime은 설치·운영 문서를 참고하세요.

기본 사용

연결 후 LLM에서 다음 순서로 사용합니다.

1. repository_status로 원격 저장소와 schema 상태를 확인합니다.
2. search_knowledge 또는 get_knowledge로 기존 지식을 읽습니다.
3. 새로운 기술 지식은 capture_knowledge로 제안합니다.
4. 결과의 privacy·completeness 검사를 확인한 뒤 apply_proposal로 커밋합니다.
5. 오래된 지식이나 반례가 발견되면 challenge_knowledge 또는 maintain_knowledge를 사용합니다.

제공되는 MCP 도구는 다음과 같습니다.

도구	용도
search_knowledge	기술 지식 검색 및 bounded health hint 확인
get_knowledge	안정적인 entry ID로 문서·근거·review 읽기
capture_knowledge	완결성·privacy·독립 코드 예시를 검사한 저장 제안 생성
challenge_knowledge	반례와 개정안을 제출하고 검증 요청
apply_proposal	승인된 제안을 원자적 GitHub commit으로 반영
maintain_knowledge	stale·중복·관계·분류 점검과 구조 변경 제안
repository_status	repository, migration, derived index 상태 진단

모든 변경은 idempotency key와 원격 HEAD 검사를 사용합니다. 충돌이 발생하면 현재 상태를 다시 검색한 뒤 새 제안을 만들도록 안내합니다.

설정

기본값은 보수적으로 설정되어 있습니다.

schema_version: 1
repository:
  slug: owner/private-knowledge
publishing:
  approval_mode: always
privacy:
  fail_closed: true
search:
  lexical: true
  vector:
    enabled: false
maintenance:
  inline_budget_ms: 200
logging:
  content: never

대부분의 사용자는 init이 생성한 설정만 사용하면 됩니다. 승인 모드나 조직별 차단 규칙이 필요할 때만 init --advanced 또는 --privacy-rules-file을 사용하세요. 예시는 examples/privacy-rules.yaml에 있습니다.

세부 옵션과 호환성 규칙은 설정·운영 문서, schema는 spec/schemas를 참고하세요.

데이터와 보안 원칙

• private GitHub repository가 지식의 유일한 SSOT이며, 로컬 SQLite 인덱스는 삭제 후 다시 만들 수 있습니다.
• 업무 원문, 사내 식별자, credential, private source code를 knowledge entry에 넣지 않습니다.
• 코드 설명이 필요하면 원본과 독립적인 새 예시를 작성합니다.
• PAT는 config에 복사되지 않으며 read-only bind mount로 컨테이너에 전달됩니다.
• config, PAT, private Markdown과 업무 코드가 Git working tree나 Docker build context에 들어가지 않도록 합니다.
• 로그에는 지식 본문과 비밀을 기록하지 않습니다.

위협 모델과 privacy pipeline은 보안·프라이버시 문서, 취약점 신고 절차는 SECURITY.md를 확인하세요.

지식 저장소 형식

GitHub repository에는 knowledge entry, evidence card, challenge review, regression case와 생성된 INDEX.md가 canonical schema에 따라 저장됩니다. 디렉터리·frontmatter·관계 규칙은 지식 저장소 명세, 검색과 갱신 정책은 검색·지식 생명주기에 설명되어 있습니다.

업그레이드

release image는 mutable tag 대신 검증된 image digest를 사용합니다. runtime init으로 stable Compose descriptor를 만들면 PAT 교체나 이미지 업데이트 뒤에도 MCP 클라이언트를 재등록할 필요가 없습니다. upgrade --check로 호환성을 먼저 확인한 후 runtime update-image --verified-release를 실행합니다. schema·설정 migration은 버전별 migration 파일과 함께 자동 적용되며 원본 설정을 임의로 덮어쓰지 않습니다.

자세한 절차는 마이그레이션 문서와 설치·운영 문서를 참고하세요.

개발

기여하려면 Node.js 24 이상 환경에서 다음을 실행합니다.

npm ci
npm run check

테스트·평가 명령과 변경 규칙은 테스트·평가 문서와 시스템 아키텍처를 참고하세요.

더 읽기

• 제품 개요와 요구사항
• 연구 근거
• 시스템 아키텍처
• MCP API 명세
• GitHub 저장·동시성
• 보안·프라이버시

패키지 라이선스는 Apache-2.0입니다.