# 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
- `curl`
- 지식 저장소로 사용할 **private GitHub repository**
- 해당 repository만 선택한 fine-grained PAT
  - `Metadata: Read-only`
  - `Contents: Read and write`
  - Pull requests, Actions, Administration 권한은 부여하지 않음
- 소스에서 빌드하거나 기여할 경우에만 Node.js 24 이상과 Git

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

## 자격 증명 없이 먼저 보기

GitHub repository나 PAT를 만들기 전에 release image를 메모리 모드로 MCP 클라이언트에 연결할 수 있습니다. 이 모드의 데이터는 프로세스가 끝나면 사라지며 도구 계약을 평가하는 용도로만 사용합니다.

```bash
PREVIEW_DIR="$(mktemp -d)"
curl -fsSL \
  https://github.com/One-armed-boy/auto-knowledge-sync-mcp/releases/latest/download/image-digest.txt \
  --output "$PREVIEW_DIR/image-digest.txt"
IMAGE_REF="$(tr -d '\r\n' < "$PREVIEW_DIR/image-digest.txt")"
docker pull "$IMAGE_REF"

# 둘 중 사용하는 클라이언트 하나에 등록
claude mcp add --transport stdio --scope user auto-knowledge-sync-preview \
  -- docker run --rm -i "$IMAGE_REF" serve --stdio --memory
codex mcp add auto-knowledge-sync-preview \
  -- docker run --rm -i "$IMAGE_REF" serve --stdio --memory
```

연결 후 `repository_status`, `prepare_capture`, `capture_knowledge`를 호출해 저장 없는 흐름을 확인할 수 있습니다. 평가가 끝나면 클라이언트에서 `auto-knowledge-sync-preview` 등록을 제거하십시오.

소스 checkout으로 평가하려면 `npm ci && npm run build` 후 `node dist/cli.js serve --stdio --memory`를 실행해도 됩니다.

## 빠른 시작

### 1. 검증된 release image 준비

```bash
INSTALL_DIR="${XDG_CONFIG_HOME:-$HOME/.config}/auto-knowledge-sync"
mkdir -p "$INSTALL_DIR"
curl -fsSL \
  https://github.com/One-armed-boy/auto-knowledge-sync-mcp/releases/latest/download/image-digest.txt \
  --output "$INSTALL_DIR/image-digest.txt"
IMAGE_REF="$(tr -d '\r\n' < "$INSTALL_DIR/image-digest.txt")"
docker pull "$IMAGE_REF"
```

`image-digest.txt`에는 mutable tag가 아닌 검증된 `ghcr.io/...@sha256:...` 참조가 들어 있습니다.

### 2. PAT 파일과 설정 만들기

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

```bash
CONFIG_DIR="${XDG_CONFIG_HOME:-$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"

docker run --rm -i \
  --mount type=bind,src="$PAT_FILE",dst=/run/secrets/github_pat,readonly \
  --mount type=bind,src="$CONFIG_DIR",dst=/output \
  "$IMAGE_REF" init \
  --repository GITHUB_OWNER/PRIVATE_KNOWLEDGE_REPOSITORY \
  --output-dir /output
```

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

```text
$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용 등록 명령을 출력합니다.

```bash
CONFIG_FILE="$CONFIG_DIR/config.yaml"

docker run --rm -i \
  --mount type=bind,src="$CONFIG_FILE",dst=/config/config.yaml,readonly \
  --mount type=bind,src="$PAT_FILE",dst=/run/secrets/github_pat,readonly \
  "$IMAGE_REF" doctor \
  --config-file /config/config.yaml \
  --client-commands \
  --image-ref "$IMAGE_REF" \
  --host-config-file "$CONFIG_FILE" \
  --host-token-file "$PAT_FILE"
```

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

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

PAT 교체나 image upgrade에도 클라이언트를 재등록하지 않는 digest 고정 Compose runtime은 [설치·운영 문서](docs/09-installation-operations.md)를 참고하세요. 소스 빌드는 개발 절에만 필요합니다.

## 기본 사용

조회와 저장은 서로 다른 흐름입니다.

기술 조사, 설계 결정, dependency·version 선택 또는 troubleshooting을 시작할 때 저장된 지식이 도움이 될 수 있으면 `search_knowledge`를 먼저 호출합니다. 관련 결과가 있으면 `get_knowledge`로 본문과 근거를 읽습니다. 검색 결과는 과거의 기술 지식과 탐색 단서이며 최신 권위가 아니므로, 변동 가능한 사실은 현재의 권위 있는 공개 출처로 다시 확인합니다. MCP가 없거나 결과가 없으면 원래 작업을 계속합니다.

저장은 재사용할 수 있는 결론이 안정된 뒤에만 시작합니다.

1. 결론이 생긴 시점에 `prepare_capture`로 완결된 skeleton을 받아 채웁니다.
2. `capture_knowledge`로 제안하고 privacy·completeness·portability 검사를 확인합니다.
3. 승인이 필요한 경우 `apply_proposal`로 커밋합니다.
4. 약한 근거·과도한 범위·문장 손상 같은 품질 신호는 `audit_knowledge`로 점검합니다.
5. 오래된 지식이나 반례가 발견되면 `challenge_knowledge` 또는 `maintain_knowledge`를 사용합니다.

별도 언어 설정은 필요하지 않습니다. 호스트 LLM은 기본 `content_language: auto`에서 마지막으로 실질적인 사용자 메시지의 언어를 감지해 제목·주장·설명·근거 요약을 같은 언어로 작성합니다. 사용자가 특정 문서에 다른 언어를 명시하면 그 요청이 우선합니다. MCP에는 언어 감지를 위한 대화 원문을 보내지 않으며, 13개 고정 표제와 enum·ID 같은 기계 구조만 호환성을 위해 영어로 유지합니다.

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

| 도구 | 용도 |
|---|---|
| `prepare_capture` | 저장 없이 ID·13개 섹션·근거 카드·이식성 선언 skeleton 생성 |
| `search_knowledge` | 기술 조사·설계·version 판단 전에 수행하는 read-only 지식 검색 |
| `get_knowledge` | 안정적인 entry ID로 문서·근거·review 읽기 |
| `capture_knowledge` | 완결성·privacy·독립 코드 예시를 검사한 저장 제안 생성 |
| `challenge_knowledge` | 반례와 개정안을 제출하고 검증 요청 |
| `apply_proposal` | 승인된 제안을 원자적 GitHub commit으로 반영 |
| `maintain_knowledge` | stale·중복·관계·분류 점검과 구조 변경 제안 |
| `audit_knowledge` | 근거·검색 회귀·언어·검증·범위 품질을 읽기 전용으로 감사 |
| `repository_status` | repository, migration, derived index 상태 진단 |

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

`provisional`은 미완성 초안이 아니라 검증 한계가 명시된 **완결 문서**입니다. 사내 맥락이 최종 주장에 영향을 줬다면 `derivation: generalized-private-context`와 `portability_attestation.private_context_influenced: true`를 함께 사용해야 합니다. 공개 자료나 새 합성 재현만으로 최종 주장이 완결됐다면 해당 evidence basis를 `derivation`으로 사용합니다.

## LLM의 자동 호출 돕기

서버는 MCP 초기화 시 검색 시점과 최신 자료 재검증 원칙을 직접 안내하므로 별도 설정 없이도 동작합니다. 자동 호출률을 더 높이고 싶다면 release에 포함된 공용 Agent Skill을 사용자 scope에 설치할 수 있습니다.

```bash
INTEGRATION_DIR="$(mktemp -d)"
curl -fsSL \
  https://github.com/One-armed-boy/auto-knowledge-sync-mcp/releases/latest/download/host-integrations.tar.gz \
  --output "$INTEGRATION_DIR/host-integrations.tar.gz"
tar -xzf "$INTEGRATION_DIR/host-integrations.tar.gz" -C "$INTEGRATION_DIR"
mkdir -p "$HOME/.claude/skills" "$HOME/.codex/skills"
cp -R "$INTEGRATION_DIR/integrations/agent-skills/auto-knowledge-sync" "$HOME/.claude/skills/"
cp -R "$INTEGRATION_DIR/integrations/agent-skills/auto-knowledge-sync" "$HOME/.codex/skills/"
```

Skill은 read-only 검색과 엄격한 capture 흐름을 분리하고, 기술 조사·설계·troubleshooting 같은 trigger만 짧게 상시 노출합니다. Claude Code와 Codex별 선택적 reminder hook, 기존 설정과 안전하게 병합하는 방법은 [설치·운영 문서](docs/09-installation-operations.md#10-호스트-활성화)를 참고하세요. hook 없이도 MCP의 핵심 기능은 동일하게 동작합니다.

## 설정

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

```yaml
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`](examples/privacy-rules.yaml)에 있습니다.

지식 작성 언어는 설치 설정이 아니라 현재 대화에서 자동으로 선택됩니다. 따라서 같은 저장소에서도 사용자의 대화 언어를 자연스럽게 따르며, 필요한 문서에만 `prepare_capture.content_language`로 `ko`, `en`, `ja`, `ko-KR` 같은 BCP 47 태그를 명시할 수 있습니다.

`approval_mode: never`도 privacy hard gate를 끄지 않으며, private context가 최종 주장에 영향을 준 항목은
항상 high risk로 분류되어 사람 승인을 요구합니다.

세부 옵션과 호환성 규칙은 [설정·운영 문서](docs/09-installation-operations.md), schema는 [`spec/schemas`](spec/schemas)를 참고하세요.

## 데이터와 보안 원칙

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

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

## 지식 저장소 형식

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

## 업그레이드

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

자세한 절차는 [마이그레이션 문서](docs/10-migrations.md)와 [설치·운영 문서](docs/09-installation-operations.md)를 참고하세요.

## 개발

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

```bash
npm ci
npm run check
```

테스트·평가 명령과 변경 규칙은 [테스트·평가 문서](docs/11-testing-evaluation.md)와 [시스템 아키텍처](docs/03-architecture.md)를 참고하세요.

## 더 읽기

- [제품 개요와 요구사항](docs/01-product-spec.md)
- [연구 근거](docs/02-research-basis.md)
- [시스템 아키텍처](docs/03-architecture.md)
- [MCP API 명세](docs/05-mcp-api.md)
- [GitHub 저장·동시성](docs/07-github-storage.md)
- [보안·프라이버시](docs/06-security-privacy.md)

패키지 라이선스는 [Apache-2.0](LICENSE)입니다.