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 이상이 필요합니다.

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

정상 실행 확인:

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를 지원하는 다른 클라이언트에서도 사용할 수 있습니다.

사용 예시

첨부 문서를 읽어 마크다운으로 변환해줘.
이 내용을 개조식 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	결과 파일 링크 보관 시간