School Record Validator MCP

처음 오셨나요? 교사용 안내 홈페이지에서 프로젝트 소개, Remote MCP 연결 방법, 결과 읽는 법을 먼저 확인하세요.

2026학년도 초등학교 학교생활기록부 문안을 교육부 공식 문서에 근거해 검토하는 교육·실습용 MCP 서버입니다. AI가 7개 도구를 직접 호출해 금지·검토 표현, 입력 길이, 작성 근거, 관련 규칙과 원문 인용을 구조화된 결과로 확인합니다.

이 프로젝트는 현직 교사 AI찬우쌤이 학교 현장의 AI 활용 실습과 교육 공공성에 기여하기 위해 만들었습니다. AI찬우쌤은 교육자를 위한 AI 활용 서비스 classddok.com을 운영하고 있습니다.

결과 상태 읽는 법

검증 결과는 문안 자체와 작성 경위 확인을 분리합니다. contentStatus: pass는 문안에서 현재 규칙팩의 금지·검토 표현이 탐지되지 않았다는 뜻이고, 작성 경위 정보가 빠진 경우에는 needsContext에 중립적인 확인 항목이 표시됩니다. 정보가 없다는 이유만으로 문안을 위반으로 판정하지 않습니다.

종합 status는 다음 우선순위를 따릅니다.

needs_context는 기재 위반이나 위험 판정이 아니므로 경고·오류 색상 대신 “최종 기재 전 확인”으로 표시해야 합니다. 자세한 JSON 계약은 검증 결과 계약을 참고하세요.

Related MCP server: Text Analyzer

무엇을 지원하나요?

• 규칙팩: kr-moe-school-record-elementary-2026.1

• 범위: 2026학년도 초등학교 전용

• 공식 자료: 교육부 문서 8개

• 검색 말뭉치: 고유 청크 515개 중 사람 검토를 거친 활성 청크 400개

• 근거 인용: 사람이 확인한 정확한 인용 12개

• 실행 방식: 로컬 stdio MCP와 URL 기반 Remote MCP

• 원격 전송: Streamable HTTP /mcp 및 구형 SSE 호환 /sse

중학교와 고등학교 기재요령은 v1의 검색과 판정에 포함하지 않습니다.

AI가 정말 직접 사용하나요?

네. MCP를 지원하는 AI 클라이언트에 서버를 한 번 등록하면 AI가 도구 목록과 입력 스키마를 읽고 필요할 때 직접 호출합니다.

1. 사용자가 “이 행동특성 문안을 검토해줘”라고 요청합니다.

2. AI가 validate_record_text를 호출합니다.

3. 필요한 경우 explain_record_rule, search_record_guidance, get_source_excerpt를 이어서 호출합니다.

4. MCP가 판정, 규칙 ID, 문서 위치, 검증 인용을 반환합니다.

5. AI가 결과를 사용자에게 설명합니다.

모델이 항상 자율적으로 도구를 고른다고 보장할 수는 없습니다. 첫 사용에서는 “school-record-validator MCP를 반드시 사용해”라고 명시하면 확인하기 쉽습니다.

도구 7개

빠른 설치

요구 사항은 Node.js 22.18.0 이상입니다.

git clone https://github.com/ARTHONG1/-school-record-validator-mcp.git
cd school-record-validator-mcp
npm ci
npm run build
npm run test:e2e

Windows PowerShell의 실행 정책 때문에 npm.ps1이 차단되면 npm 대신 npm.cmd를 사용하세요.

npm.cmd ci
npm.cmd run build
npm.cmd run test:e2e

로컬 stdio MCP 등록

로컬 모드는 학생 문안을 컴퓨터 밖으로 전송하지 않습니다. MCP 설정의 경로를 실제 설치 위치로 바꾸세요.

{
  "mcpServers": {
    "school-record-validator": {
      "command": "node",
      "args": ["C:\\path\\to\\school-record-validator-mcp\\dist\\index.js"]
    }
  }
}

Codex CLI를 사용할 수 있다면 다음과 같이 등록할 수 있습니다.

codex mcp add school-record-validator -- node "/absolute/path/school-record-validator-mcp/dist/index.js"
codex mcp get school-record-validator

등록 후 AI 클라이언트를 완전히 종료했다가 다시 열고 새 대화에서 시험하세요.

Remote MCP 등록 화면

Google Cloud Run 등에 배포해 서비스 URL을 받은 뒤 다음 값을 입력합니다.

현재 공개 배포는 HTTP 전용이며 별도 인증 헤더가 필요하지 않습니다. SSE는 비활성화되어 있으므로 신규 연결에는 HTTP를 사용하세요.

공개 서버는 요청 횟수를 별도로 제한하지 않습니다. HTTP 본문은 최대 10MB, 문안은 건당 최대 200,000자, 배치는 최대 100건이며 Cloud Run 최대 인스턴스 1과 월 예산 알림으로 비용을 통제합니다.

상세 배포 절차는 Remote MCP와 Google Cloud Run 배포를 참고하세요.

Remote MCP 로컬 시험

npm.cmd run build
$env:PORT="8080"
$env:MCP_ENABLE_LEGACY_SSE="false"
npm.cmd run start:remote

다른 터미널에서 상태를 확인합니다.

Invoke-RestMethod http://localhost:8080/health

Remote MCP 엔드포인트는 다음과 같습니다.

• 권장 HTTP: http://localhost:8080/mcp

• SSE 호환: http://localhost:8080/sse

• 상태 확인: http://localhost:8080/health (/healthz도 로컬에서 지원)

바로 써보는 요청문

school-record-validator MCP의 validate_record_text 도구를 반드시 사용해서
“교외 영어경시대회에서 대상을 수상했으며 전교에서 가장 성실함”을
2026학년도 초등학교 행동특성 및 종합의견 기준으로 검사하고,
발견된 규칙의 공식 근거도 설명해 줘.

official 프로필은 교육부 공식 규칙만 실행합니다. official_plus_editorial은 공식 규칙에 항상, 완벽하게, 전교에서 가장, 가정 내 활동, 진로 단정 표현과 같은 자체 편집 경고를 추가합니다. editorial-caution은 교육부의 공식 금지 규정이 아닙니다.

개인정보와 보안

교육·실습용 공개 서버에는 실제 학생의 이름, 학번, 연락처 등 식별정보를 입력하지 말고 가명·비식별 예시만 사용하세요. 실제 학교 업무에 원격 서버를 사용하려면 학교 개인정보 처리 기준과 적법한 처리 근거를 별도로 검토해야 합니다.

길이 검사

CRLF를 LF로 정규화한 뒤 UTF-8 바이트를 계산합니다. 한글은 일반적으로 3Byte, 영문·숫자·Enter는 1Byte입니다.

공식 자료와 출처

교육부 「2026 학교생활기록부 기재요령(초등학교)」, 「학교생활기록 작성 및 관리지침」 교육부훈령 제555호 및 별표 7~11을 사용했습니다. 문서별 제목, 날짜, URL, SHA-256과 가공 내역은 ATTRIBUTION.md와 원본 감사 기록에 있습니다.

코드는 MIT 라이선스입니다. 교육부 공식 문서 및 문서에서 추출·가공한 데이터는 코드의 MIT 라이선스에 자동 포함되지 않습니다. 배포·재사용 전 DATA_LICENSE.md와 원 게시물의 최신 공공누리·권리표시를 확인하세요.

검증 명령

npm ci
npm run typecheck
npm test
npm run build
npm run test:e2e
npm run verify:site
npm pack --dry-run

공식 원본을 로컬에 보유한 유지관리자는 SCHOOL_RECORD_SOURCE_DIR을 지정해 해시와 추출 결과를 추가 검증할 수 있습니다.

$env:SCHOOL_RECORD_SOURCE_DIR="C:\path\to\official-sources"
npm.cmd run verify:sources
node --test tests/source-integration.test.ts

문제 해결

AI가 도구를 찾지 못합니다

MCP 등록 후 AI 앱을 완전히 종료하고 다시 실행한 다음 새 대화를 여세요. 로컬 모드는 dist/index.js, Remote MCP HTTP는 /mcp URL을 사용해야 합니다.

codex 명령을 찾을 수 없습니다

Codex Desktop과 Codex CLI의 PATH 등록은 별개일 수 있습니다. 앱의 MCP 설정 화면을 사용하거나 Codex CLI 실행 파일의 절대 경로를 사용하세요.

Remote MCP가 404를 반환합니다

HTTP 선택 시 URL 끝이 /mcp, SSE 선택 시 /sse인지 확인하세요. SSE를 환경변수로 비활성화했다면 /sse는 제공되지 않습니다.

빌드 후에도 이전 동작이 보입니다

npm run build를 다시 실행하고 로컬 MCP 프로세스 또는 배포된 Cloud Run 리비전을 재시작하세요.

프로젝트 상태

이 저장소는 교육·실습용 오픈소스 프로젝트입니다. 현재 규칙팩의 적용 범위와 알려진 한계는 docs/limitations.md, 규칙별 감사 결과는 docs/rule-audit.md, 공식 자료 갱신 절차는 docs/source-update.md를 참고하세요.