# Kordoc Remote MCP

`kordoc`을 ChatGPT의 사용자 지정 MCP 앱에서 호출할 수 있도록 Streamable HTTP로 감싼 서버입니다.

제공 도구:

- `parse_document`: HWP/HWPX/PDF/XLS/XLSX/DOCX → Markdown/JSON
- `generate_document`: Markdown → HWPX
- `patch_document`: 원본 HWP/HWPX 서식을 유지하여 텍스트 수정
- `fill_form`: HWPX 양식 자동 입력
- `validate_document`: HWPX 구조 및 공문서 표기 검사

## 먼저 알아둘 점

ChatGPT 사용자 지정 MCP 앱은 인터넷에서 접근 가능한 HTTPS 주소가 필요합니다. PC의 `localhost` 주소는 ChatGPT에 직접 등록할 수 없습니다. 또한 ChatGPT에서 개발자 모드 및 사용자 지정 앱을 사용할 수 있는 계정·작업공간 권한이 필요합니다.

업로드 문서는 서버의 임시 폴더에서 처리 후 삭제됩니다. 결과 파일 링크는 기본 30분 후 만료됩니다. 중요한 개인정보가 포함된 문서는 조직의 보안정책에 맞는 서버에 직접 배포하세요.

## 로컬 실행

Node.js 20 이상이 필요합니다.

```bash
cp .env.example .env
npm install
PUBLIC_BASE_URL="http://localhost:3000" npm start
```

정상 실행 확인:

```bash
curl http://localhost:3000/health
```

## Render 배포

1. 이 폴더를 본인의 비공개 GitHub 저장소에 올립니다.
2. Render에서 `New +` → `Blueprint`를 선택하고 저장소를 연결합니다.
3. 배포 후 서비스의 `PUBLIC_BASE_URL` 환경변수를 Render가 발급한 주소로 지정합니다. 예: `https://kordoc-remote-mcp.onrender.com`
4. 다시 배포한 뒤 `https://발급주소/health`가 `{"ok":true,...}`를 반환하는지 확인합니다.

무료 인스턴스는 장시간 미사용 시 잠들 수 있어 첫 요청이 느릴 수 있습니다. 업무용이면 유료 인스턴스 또는 사내 서버를 권장합니다.

## ChatGPT 연결

개발자 모드가 허용된 ChatGPT 웹 작업공간에서 다음 순서로 등록합니다.

1. `설정 → 앱 → 고급 설정`에서 개발자 모드를 켭니다.
2. `설정 → 앱 → 만들기`를 선택합니다.
3. MCP 서버 주소에 `https://발급주소/mcp`를 입력합니다.
4. 인증은 `없음`으로 선택합니다.
5. 연결 테스트 후 저장합니다.

AI API 키는 필요하지 않습니다. `MCP_API_KEY`도 기본적으로 비워두며, 공개 서버를 비밀번호로 보호하고 싶을 때만 임의의 문자열을 지정하고 ChatGPT에 Bearer 토큰으로 동일하게 입력합니다.

ChatGPT Plus 개인 계정에서 `개발자 모드` 또는 `앱 만들기`가 보이지 않으면 해당 계정에서는 원격 MCP를 직접 등록할 수 없습니다. 이 서버는 Claude/Cursor 등 Streamable HTTP MCP를 지원하는 다른 클라이언트에서도 사용할 수 있습니다.

## 사용 예시

```text
첨부 문서를 읽어 마크다운으로 변환해줘.
이 내용을 개조식 HWPX 보고서로 만들어줘.
원본 서식을 유지하고 ‘점장’을 모두 삭제한 수정본을 만들어줘.
완성된 문서의 구조와 공문서 표기를 검사해줘.
```

도구에는 문서를 전달할 공개 또는 서명된 HTTPS URL이 필요합니다. 작은 파일은 Base64로도 전달할 수 있습니다. ChatGPT가 첨부파일의 임시 URL을 도구에 전달할 수 없는 환경에서는 별도의 업로드 엔드포인트나 저장소 연동이 추가로 필요합니다.

## 보안 설정

- 공개 주소를 다른 사람이 사용하지 못하게 하려면 `MCP_API_KEY`에 최소 32자 이상의 무작위 값을 설정하세요.
- 저장소에 `.env` 파일이나 실제 인증키를 올리지 마세요.
- 민감 문서에는 무료 공용 호스팅보다 사내 또는 전용 서버를 사용하세요.
- `MAX_FILE_MB`와 `FILE_TTL_MINUTES`를 필요한 최소값으로 유지하세요.
- 운영 환경에서는 네트워크 접근제어, 악성파일 검사, 요청 제한 및 감사로그를 추가하세요.

## 환경변수

| 변수 | 기본값 | 설명 |
|---|---:|---|
| `PORT` | `3000` | HTTP 포트 |
| `MCP_API_KEY` | 빈 값 | 선택형 Bearer 인증키; 비우면 인증 없음 |
| `PUBLIC_BASE_URL` | 로컬 주소 | 결과 링크에 사용할 공개 주소 |
| `MAX_FILE_MB` | `25` | 입력 파일 최대 크기 |
| `FILE_TTL_MINUTES` | `30` | 결과 파일 링크 보관 시간 |