ssampin-ai-bridge 0.1.0 → 0.2.0

package/README.md

@@ -1,63 +1,87 @@
 # ssampin-ai-bridge
 
-쌤핀(SsamPin, 교사용 데스크톱 앱)의 **로컬 데이터를 외부 AI와 API 키 없이** 안전하게 연결하는 브릿지(MCP 서버 + 등록 CLI). Claude·Codex(GPT)·Antigravity(Gemini) 세 가지 AI 클라이언트를 **동등하게** 지원합니다.
+쌤핀(SsamPin, 교사용 데스크톱 대시보드)의 **로컬 데이터를 외부 AI와 API 키 없이** 안전하게 연결하는 브릿지(MCP 서버 + 등록 CLI)입니다. Claude Desktop · Codex(GPT) · Antigravity(Gemini) 세 가지 AI 도구를 **동등하게** 지원합니다.
 
 > 학생·교사 개인정보는 **토큰화·탈식별·동의 게이트**를 거쳐 모델로 나갑니다. 자세한 개인정보 모델과 정직한 한계는 https://ssampin.com/ai-bridge 를 참고하세요.
 
-## 빠른 시작 (B안 · CLI)
+대부분의 선생님은 **쌤핀 앱 안에서 "설정 → AI 연결" 원클릭**으로 연결합니다(이 패키지를 직접 설치할 필요 없음 — 앱이 동봉 서버를 실행). 아래는 터미널에 익숙한 사용자를 위한 방법입니다.
 
-> 대부분의 선생님은 **쌤핀 앱 안에서 "설정 → AI 연결" 원클릭**(A안)을 쓰면 됩니다. 아래는 터미널에 익숙한 사용자를 위한 방법입니다.
+## 빠른 시작 (npx / CLI)
 
 ```bash
 # 전역 설치 권장(등록되는 서버 경로가 안정적입니다)
 npm install -g ssampin-ai-bridge
 
-# 3개 클라이언트 중 원하는 곳에 등록
-ssampin-ai-bridge register claude       --data-dir "%APPDATA%/쌤핀/data"
-ssampin-ai-bridge register codex        --data-dir "%APPDATA%/쌤핀/data"
-ssampin-ai-bridge register antigravity  --data-dir "%APPDATA%/쌤핀/data"
+# 3종 클라이언트 중 쓰는 곳에 등록 (--data-dir 생략 시 %APPDATA%/ssampin/data 자동 탐지)
+ssampin-ai-bridge register claude       --data-dir "%APPDATA%/ssampin/data"
+ssampin-ai-bridge register codex        --data-dir "%APPDATA%/ssampin/data"
+ssampin-ai-bridge register antigravity  --data-dir "%APPDATA%/ssampin/data"
+
+# 내용 노출/쓰기를 켜려면(기본 꺼짐):
+ssampin-ai-bridge register claude --data-dir "..." --allow-content --allow-write
+
+# 미리보기(실제 변경 없음):
+ssampin-ai-bridge register codex --data-dir "..." --dry-run
 ```
 
-또는 설치 없이 한 번만:
+설치 없이 한 번만:
 
 ```bash
-npx ssampin-ai-bridge register claude --data-dir "%APPDATA%/쌤핀/data"
+npx ssampin-ai-bridge register claude --data-dir "%APPDATA%/ssampin/data"
 ```
 
 등록 후 해당 AI 앱(또는 codex)을 **재시작**하면 도구가 나타납니다.
 
-## 클라이언트별 등록 메커니즘 (동등 지원)
+## 클라이언트별 등록 메커니즘 (3종 동등)
 
-| 클라이언트 | 메커니즘 |
-|---|---|
-| **claude** (Claude Desktop) | 설정 파일 `claude_desktop_config.json` 의 `mcpServers` 안전 병합(기존 서버 보존 + 자동 백업) |
-| **codex** (GPT) | `codex mcp add` 실행(codex CLI 필요 — 미설치 시 실행할 명령을 안내) |
-| **antigravity** (Gemini) | 설정 파일 `~/.gemini/antigravity/mcp_config.json` 안전 병합(보존 + 백업) |
+| 클라이언트 | 메커니즘 | 설정 위치 |
+|---|---|---|
+| **claude** (Claude Desktop) | 설정 JSON `mcpServers` 안전 병합(기존 서버 보존 + 자동 백업) | `%APPDATA%/Claude/claude_desktop_config.json` (mac: `~/Library/Application Support/Claude/…`) |
+| **codex** (GPT) | `codex mcp add` 실행. 미설치 시 실행할 명령 안내 | codex CLI 관리 |
+| **antigravity** (Gemini) | 설정 JSON `~/.gemini/antigravity/mcp_config.json` 안전 병합(보존 + 백업) | Antigravity 관리 |
+
+세 경우 모두 기존 설정을 **백업**하고 다른 서버 항목·최상위 키를 **보존**합니다.
+
+## 제공 도구
 
-## 게이트 (기본 전부 꺼짐)
+게이트(`--allow-content` / `--allow-write`)는 기본 꺼짐이며, 옵션을 명시할 때만 켜집니다. 옵션이 없으면 명단·자리 같은 **토큰화된 정보만** 다룹니다.
+
+| 분류 | 도구 | 게이트 |
+|---|---|---|
+| 명단·자리 | `list_students`, `get_seating` | — |
+| 생기부 보조 | `get_record_guidelines`, `check_record_draft`, `get_record_evidence`(근거 자료 읽기), `write_record_draft`(영역별 초안 저장) | 읽기 일부 `--allow-content` · `write_record_draft` `--allow-write` |
+| 관찰·누가기록 | `get_observations`, `add_observation`, `get_homeroom_notes`, `set_homeroom_note` | 읽기 `--allow-content` · 쓰기 `--allow-write` |
+| 출결 | `get_homeroom_attendance`, `set_homeroom_attendance`, `get_attendance_records`, `set_attendance_record`, `delete_attendance_record` | 읽기 `--allow-content` · 쓰기 `--allow-write` |
+| 일정·할 일·메모·북마크 | `get_events`/`ssampin_create_event`/`update_event`/`delete_event`, `get_todos`/`ssampin_create_todo`/`update_todo`/`complete_todo`/`delete_todo`, `get_memos`/`create_memo`/`update_memo`/`delete_memo`, `get_bookmarks`/`create_bookmark`/`create_bookmark_group`/`update_bookmark`/`delete_bookmark` | 읽기 `--allow-content` · 쓰기 `--allow-write` |
+| 요약 | `get_weekly_summary` | `--allow-content` |
+
+> `get_record_evidence`(v0.2)는 교사가 쌤핀의 '근거 자료' 서브페이지에 모아둔 자료를 토큰화·탈식별해 읽습니다. 외부 AI가 영역별 생기부 초안을 쓸 때 **근거에 기반**하도록 돕는 읽기 전용 도구입니다.
+
+## 게이트 (기본 모두 꺼짐)
 
 | 옵션 | 효과 |
 |---|---|
-| `--allow-content` | 관찰 내용 원문 노출(`get_observations`) 허용 |
-| `--allow-write` | 관찰 기록 쓰기(`add_observation`) 허용 |
+| `--allow-content` | 관찰·기록 원문 노출(`get_observations`·`get_record_evidence` 등) 허용 |
+| `--allow-write` | 기록·출결·초안 쓰기(`add_observation`·`set_homeroom_attendance`·`write_record_draft` 등) 허용 |
 
-옵션을 주지 않으면 명단·자리 같은 **토큰화된 정보만** 다룹니다.
+## 보안·프라이버시 (꼭 읽어주세요)
 
-## 안전·프라이버시 (꼭 읽으세요)
-
-- **토큰화는 "실명만" 가립니다.** 토큰화만으로 완전한 익명이 되지 않으며, 관찰 내용 맥락으로 재식별될 수 있습니다.
-- **`get_observations` 는 관찰 원문이 외부 AI로 나갑니다.** 게이트/동의가 켜진 경우에만 동작합니다.
-- **생기부는 법정 기록입니다.** 점검 도구는 어휘 근거 확인일 뿐, 모든 문장은 교사가 직접 사실 확인·책임져야 합니다.
+- **토큰화는 "익명"과 다릅니다.** 토큰만으로 신원이 직접 드러나지 않지만, 관찰 내용 맥락으로 재식별될 수 있습니다.
+- **원문은 외부 AI로 나갑니다.** `get_observations`·`get_record_evidence` 등 내용 노출 도구는 게이트 동의가 켜진 경우에만 동작합니다.
+- **생기부는 법정 기록입니다.** `check_record_draft`·`write_record_draft`는 보조 도구일 뿐, 모든 문장은 교사가 직접 사실 확인·책임지며 자동 확정되지 않습니다. 생성형 AI 문장의 단순 전사는 기재요령상 금지입니다.
+- **외부 AI 제공자 정책 적용.** 연결한 AI(Anthropic·OpenAI·Google 등)에 전달된 데이터에는 그쪽 처리 정책이 적용됩니다. 절대적 프라이버시가 필요하면 로컬 LLM(Ollama 등)을 클라이언트로 쓰면 데이터가 기기를 떠나지 않습니다.
 
 ## 명령
 
 ```
-ssampin-ai-bridge register <claude|codex|antigravity|gemini> [--data-dir <경로>] [--allow-content] [--allow-write] [--name <이름>] [--dry-run]
+ssampin-ai-bridge register <claude|codex|antigravity> [--data-dir <경로>] [--allow-content] [--allow-write] [--name <이름>] [--dry-run]
 ```
 
-- `--dry-run` : 실제 변경 없이 수행될 등록 계획(JSON)만 출력
+- `--dry-run` : 실제 변경 없이 등록 계획(JSON)만 출력
 - `ssampin-mcp` : MCP 서버를 직접 실행하는 진입(보통 클라이언트가 자동 실행)
 
+자세한 안내: https://ssampin.com/ai-bridge · 개인정보처리방침: https://ssampin.com/privacy
+
 ## 라이선스
 
 GPL-3.0