ssampin-ai-bridge

쌤핀(SsamPin, 교사용 데스크톱 대시보드)의 로컬 데이터를 외부 AI와 API 키 없이 안전하게 연결하는 브릿지(MCP 서버 + 등록 CLI)입니다. Claude Desktop · Codex(GPT) · Antigravity(Gemini) 세 가지 AI 도구를 동등하게 지원합니다.

학생·교사 개인정보는 토큰화·탈식별·동의 게이트를 거쳐 모델로 나갑니다. 자세한 개인정보 모델과 정직한 한계는 https://ssampin.com/ai-bridge 를 참고하세요.

대부분의 선생님은 쌤핀 앱 안에서 "설정 → AI 연결" 원클릭으로 연결합니다(이 패키지를 직접 설치할 필요 없음 — 앱이 동봉 서버를 실행). 아래는 터미널에 익숙한 사용자를 위한 방법입니다.

빠른 시작 (npx / CLI)

# 전역 설치 권장(등록되는 서버 경로가 안정적입니다)
npm install -g ssampin-ai-bridge

# 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

설치 없이 한 번만:

npx ssampin-ai-bridge register claude --data-dir "%APPDATA%/ssampin/data"

등록 후 해당 AI 앱(또는 codex)을 재시작하면 도구가 나타납니다.

클라이언트별 등록 메커니즘 (3종 동등)

| 클라이언트 | 메커니즘 | 설정 위치 | |---|---|---| | 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·get_record_evidence 등) 허용 | | --allow-write | 기록·출결·초안 쓰기(add_observation·set_homeroom_attendance·write_record_draft 등) 허용 |

보안·프라이버시 (꼭 읽어주세요)

• 토큰화는 "익명"과 다릅니다. 토큰만으로 신원이 직접 드러나지 않지만, 관찰 내용 맥락으로 재식별될 수 있습니다.
• 원문은 외부 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> [--data-dir <경로>] [--allow-content] [--allow-write] [--name <이름>] [--dry-run]

• --dry-run : 실제 변경 없이 등록 계획(JSON)만 출력
• ssampin-mcp : MCP 서버를 직접 실행하는 진입(보통 클라이언트가 자동 실행)

자세한 안내: https://ssampin.com/ai-bridge · 개인정보처리방침: https://ssampin.com/privacy

라이선스

GPL-3.0