PoomSchool Server

초등학생 자녀를 둔 다문화가정 및 북한이탈주민·북한배경 가정의 부모를 위한 학교생활 관리 Remote MCP Server입니다. MCP 식별자는 poomschool이며, Streamable HTTP 전송 방식의 Stateless MCP 서버로 구현되어 있습니다.

핵심 사용자는 아이가 아니라 부모입니다. 품스쿨은 학교 안내문을 번역만 하는 것이 아니라 부모가 해야 할 일, 아이에게 알려줄 일, 준비물, 마감일, 비용, 제출 방법 등 실행 가능한 정보로 변환합니다.

기술 스택

• TypeScript 5.9 / Node.js 20+ (Active LTS)
• 공식 MCP TypeScript SDK @modelcontextprotocol/sdk 1.29.0
• Express 5 (SDK와 함께 검증된 Streamable HTTP 전송)
• Zod 3.25
• PostgreSQL + Prisma ORM 6.19.3
• OAuth 2.1 Bearer Token 검증 (jose)
• Pino 구조화 로깅
• Vitest / ESLint / Prettier
• Docker / Docker Compose

프로젝트 구조

src/
  index.ts                 서버 엔트리포인트
  server/                  McpServer 팩토리, Streamable HTTP, 프로토콜 버전
  tools/                   10개 MCP Tool 구현
  services/                번역/분석/용어집/태스크/마크다운 렌더러, AI Provider
  auth/                    OAuth 2.1 Resource Server (Bearer 검증, scope, metadata)
  database/                Prisma 클라이언트, Repository
  security/                Origin 검증, rate limit, 보안 헤더, 로그 마스킹
  schemas/                 Zod 입력 스키마
  config/, errors/, utils/ 환경변수, 오류 처리, 유틸리티
prisma/                    schema.prisma, migrations
tests/                     unit / integration / security / privacy / multilingual / performance
docs/                      OAuth, 개인정보, 다국어 정책, PlayMCP 등록 문서
scripts/                   MCP Inspector 실행, 성능 벤치마크

로컬 실행

1) 의존성 설치

npm install

2) PostgreSQL 실행

Docker Compose로 PostgreSQL만 실행할 수도 있고, 로컬에 이미 설치된 PostgreSQL을 사용할 수도 있습니다.

docker compose up -d postgres

3) 환경변수 설정

cp .env.example .env

.env에서 최소한 DATABASE_URL을 로컬 PostgreSQL에 맞게 조정하세요. 로컬 개발에서는 AUTH_DISABLED=true, AI_PROVIDER=mock으로 시작하는 것을 권장합니다.

4) Prisma 마이그레이션

npm run prisma:migrate

5) 개발 서버 실행

npm run dev

기본적으로 http://localhost:3000/mcp에서 서비스됩니다.

테스트 / Lint / Typecheck / Build

테스트는 실제 PostgreSQL(기본값: poomschool_test 데이터베이스)과 MockAiProvider를 사용하며, 실제 Anthropic API를 호출하지 않습니다.

# 테스트용 DB 준비 (최초 1회)
createdb poomschool_test
DATABASE_URL="postgresql://<user>@localhost:5432/poomschool_test?schema=public" npx prisma migrate deploy

npm run lint
npm run typecheck
npm test
npm run build

성능 벤치마크

DATABASE_URL="postgresql://<user>@localhost:5432/poomschool_test?schema=public" npm run benchmark

list_tasks, complete_task, explain_term(용어집 캐시 hit), set_parent_preferences, analyze_notice(MockAiProvider), translate_notice(MockAiProvider), weekly_brief를 각 100회 호출해 평균/p50/p95/p99/최소/최대/실패율을 출력합니다. p99가 3,000ms를 초과하면 스크립트가 실패(exit code 1)합니다.

주의: 이 벤치마크는 MockAiProvider 기준입니다. 실제 AnthropicAiProvider의 성능은 네트워크 상태와 모델 응답 시간에 따라 달라지며 별도로 측정해야 합니다.

Docker

docker build -t poomschool-mcp .
docker compose up -d

Dockerfile은 multi-stage build, non-root 사용자 실행, healthcheck를 포함합니다. 컨테이너 시작 시 prisma migrate deploy를 실행한 뒤 서버를 시작합니다(단일 인스턴스 배포 기준이며, 다중 인스턴스 운영 시에는 마이그레이션을 별도 단계로 분리하는 것을 권장합니다).

이 개발 환경에는 Docker/Podman CLI가 설치되어 있지 않아 실제 docker build 실행 자체는 검증하지 못했습니다(미검증). Dockerfile/구성 파일은 공식 모범 사례를 따르며, Docker가 설치된 환경에서 위 명령으로 검증해야 합니다.

MCP Inspector로 검증하기

npm run dev
# 다른 터미널에서
bash scripts/inspect.sh

Inspector에서 다음을 확인합니다.

1. Streamable HTTP 연결 (http://localhost:3000/mcp)
2. initialize / protocolVersion negotiation (2025-03-26 ~ 2025-11-25)
3. tools/list: 정확히 10개, 모든 annotations 존재, 모든 description에 PoomSchool(품스쿨) 포함
4. 각 Tool 호출 결과가 한국어 Markdown인지 확인
5. 잘못된 입력에 대해 isError:true가 반환되는지 확인
6. AUTH_DISABLED=false일 때 Authorization 헤더 없이 호출하면 401이 반환되는지 확인

OAuth 설정

docs/oauth-setup.md를 참고하세요. issuer, audience, JWKS, scope, PKCE, PlayMCP Redirect URI 설정, 연동 해제 절차를 다룹니다.

PlayMCP 등록

docs/playmcp-registration.md에 등록값과 체크리스트를 정리했습니다.

개인정보 삭제 절차

1. 사용자가 삭제를 요청하거나 PlayMCP 연동을 해제하면 운영자는 oauthSubject 기준으로 UserProfile, SchoolTask, AnalysisCache 레코드를 완전히 삭제합니다.
2. 자세한 내용은 docs/privacy-policy.md와 docs/oauth-setup.md의 "데이터 삭제 절차"를 참고하세요.

다국어 정책

docs/multilingual-policy.md에 언어 자동 감지, BCP-47 사용 규칙, 원문 보존 규칙, 설명 모드(general/multicultural_parent/north_korean_parent)를 정리했습니다.

알려진 제한사항 (MVP 범위)

• 이미지 OCR, 사진 속 가정통신문 자동 인식 미지원
• 카카오톡 대화/알림톡 자동 수집 미지원
• 담임교사에게 메시지를 자동 전송하지 않음 (부모가 직접 확인 후 전송)
• 아이용 챗봇, 숙제 정답 제공 없음
• 학교 포털 자동 로그인, 교육지원 자격 자동 확정 없음
• 학교폭력 여부 판정, 의료/심리 진단, 성적/행동 평가 없음
• 정부 기관 서류 자동 제출 없음
• AnthropicAiProvider는 코드상 구현되어 있으나 실제 Anthropic API 키로 호출 검증은 이 환경에서 수행하지 못했습니다(테스트는 MockAiProvider만 사용). 실제 배포 전 AI_PROVIDER=anthropic 설정으로 별도 검증이 필요합니다.
• Docker build 자체는 이 개발 환경에 Docker CLI가 없어 미검증입니다.

운영 장애 대응 (요약)

• /healthz: 프로세스 생존 확인
• /readyz: PostgreSQL 연결 상태 확인 (SELECT 1)
• AI Provider 타임아웃(AI_TIMEOUT_MS, 기본 2500ms) 초과 시 한국어 오류 메시지 반환, 결과를 추측해 반환하지 않음
• AI 응답이 스키마 검증에 실패하면 최대 1회 복구 요청 후 실패 시 안전한 오류 반환
• 구조화 로그(Pino)에 Authorization 헤더, 안내문 원문, 부모 메시지 원문, 아이 별칭을 마스킹하여 기록하지 않음