# CharCount Keeper (글자수 지킴이)

AI가 쓴 글의 글자수를 **정확히** 세고, 목표 글자수에 **정확히** 맞추도록 결정론적 피드백을 주는 MCP 서버.

LLM은 토큰 단위로 텍스트를 처리하기 때문에 글자수를 정확히 셀 수 없습니다. 자기소개서 700자, 생활기록부 바이트 제한처럼 **글자수가 곧 합격/불합격인 상황**에서 AI는 반드시 틀립니다. 이 서버는 유니코드 표준(UAX #29 grapheme cluster) 기반으로 글자수·바이트·원고지 매수를 정확히 계산하고, 목표 대비 **정확한 초과/부족량**과 **어디를 고칠지**를 알려줘 AI가 스스로 글자수를 맞추게 합니다.

## 툴 (7개)

| 툴 | 설명 |
|---|---|
| `count_text` | 공백 포함/제외 글자수, UTF-8·EUC-KR 바이트, 어절/문장/줄/문단, 한글 음절·자모, 원고지 매수, X 가중길이 + 숨은 함정 경고(NFD 자소분리·제로폭 문자·CRLF) |
| `check_limit` | 제한 대비 판정 + **정확한 초과/부족량** (LLM 수정용 델타) |
| `count_by_segment` | 문장/문단/줄별 글자수 + 누적 — 어디를 고칠지 판단용 |
| `plan_trim` | 결정론적 감량 계획: 절단 지점, 최장 문장, 공백 정리량, 군더더기 표현 횟수 |
| `diff_count` | 수정 전후 글자수 비교 |
| `validate_platform` | X/인스타/유튜브/SEO 제한 일괄 검증 |
| `list_presets` | 지원 프리셋 목록 (자소서·NEIS·원고지·SNS) |

## 정확성 원칙

- **글자 = grapheme cluster** (`Intl.Segmenter`, UAX #29): 👨‍👩‍👧‍👦 = 1자 (JS `.length`는 11)
- **NFC 정규화 기본**: macOS 자소분리(NFD) 텍스트도 올바르게 계산 + 경고
- **CRLF → LF 정규화**: Windows 텍스트의 줄바꿈 부풀림 방지 + 경고
- **공백 3기준 동시 제공**: 공백 포함 / 공백 제외(줄바꿈 포함 제외) / 스페이스만 제외 — 기관별 기준 차이 대응
- **바이트 2기준**: UTF-8(한글 3B, 4세대 NEIS) / EUC-KR(한글 2B, 구형 시스템)
- 외부 API 의존 0 · 무상태 · 본문 저장/로깅 없음

## 개발

```bash
npm install
npm test        # 골든 테스트 26개
npm run build
npm start       # PORT 환경변수 (기본 8080), MCP 엔드포인트: POST / 또는 /mcp
```

로컬 확인:

```bash
curl http://localhost:8080/health
npx @modelcontextprotocol/inspector   # Streamable HTTP → http://localhost:8080/mcp
```

## PlayMCP 배포 (AGENTIC PLAYER 10)

1. **PlayMCP in KC** (https://playmcp.kakaocloud.io) 로그인 → "새 MCP 서버 등록"
   - **Git 소스 빌드**: 이 저장소를 GitHub(public)에 푸시 → Git URL 입력, 브랜치 `main`, Dockerfile 경로 기본값 (루트에 Dockerfile 있음 ✔)
   - 또는 **이미지 등록**: `docker build --platform linux/amd64 -t <registry>/<image>:<tag> .` 후 레지스트리 푸시
2. Status **Active** 확인 → **Endpoint URL** 복사
3. PlayMCP 개발자 콘솔 (https://playmcp.kakao.com/console) → "새로운 MCP 서버 등록" → Endpoint URL 입력 → "정보 불러오기" 성공 확인
4. **"임시 등록"** → "MCP 상세 미리보기" → "도구함에 추가" → AI 채팅에서 충분히 테스트
5. **"심사 요청"** (통상 1~2영업일, 최대 7영업일)
6. 승인 후 공개 상태를 **"전체 공개"**로 전환 → MCP 상세페이지 URL 복사
7. [공모전 페이지](https://b.kakao.com/views/PlayMCP/AGENTIC_PlAYER_10)에서 "Player 예선 참여" 비즈폼 접수 (**~7/14 마감**)

### PlayMCP 개발가이드 준수 체크리스트

- ✅ MCP 스펙 2025-03-26 ~ 2025-11-25 (양쪽 협상 확인)
- ✅ Streamable HTTP 전용, Remote, **무상태(no session)**
- ✅ 공식 TypeScript SDK (`@modelcontextprotocol/sdk`)
- ✅ 서버명/툴명에 "kakao" 미포함
- ✅ 툴 7개 (권장 3~10개)
- ✅ 툴 이름 `[A-Za-z0-9_-]`, 전 툴 `annotations` 5종(title/readOnlyHint/destructiveHint/openWorldHint/idempotentHint) 명시
- ✅ description 영문 + 서비스명 영문·국문 병기("CharCount Keeper(글자수 지킴이)") + 1,024자 이내
- ✅ 결과는 정제된 마크다운, 최소 크기
- ✅ 응답속도: 전형 입력 평균 ~33ms (요구: 평균 100ms), 최대 입력(10만 자) ~350ms (요구: p99 3,000ms)
- ✅ 광고 없음, 인증 불필요(개인정보 미취급)