korean-prompt-improver

한국어의 짧고 모호한 요청을 작업 전에 분석하여, 문맥으로 해소할 수 있는 내용은 그대로 진행하고 확인이 필요한 내용만 사용자에게 질문하는 MCP 서버입니다.

개발 배경

언어모델을 사용할 때 "이거 정리해 줘", "아까 그거 좀 더 공식적인 말투로 바꿔 줘"와 같은 짧은 요청이 자주 사용됩니다. 사람은 앞선 대화를 바탕으로 지시 대상을 자연스럽게 파악하지만, 언어모델은 지시 대상이나 작업 범위를 사용자의 의도와 다르게 판단할 수 있습니다.

반면 모호한 표현마다 질문하면 사용자의 부담이 커집니다. 본 프로젝트는 다음 문제를 중심으로 설계와 평가를 진행하였습니다.

요청을 그대로 진행해도 되는 경우와 사용자에게 확인해야 하는 경우를 어떻게 구분할 것인가

Related MCP server: Korean Law MCP

시스템 구조 (최종 V3)

flowchart LR
    U[사용자 요청 + 최근 대화] --> R{규칙 검사}
    R -- 확실한 위험 --> A[정밀 분석<br/>Claude Sonnet 4.5]
    R -- 나머지 --> L{경량 모델<br/>위험 점수}
    L -- 50점 이상 --> A
    L -- 50점 미만 --> P[원래 요청 그대로 진행]
    A --> D[결정 규칙<br/>진행 / 질문]
    D --> G[안전 검사<br/>다중 결과물·과거 지시어·외부 작업]
    G -- 판단 확정 --> O1[작업용 프롬프트]
    G -- 확인 필요 --> O2[짧은 질문 → 답변 반영]

• 분석과 결정의 분리: 언어모델은 해석 후보, 문맥 근거, 작업 영향만 분석하고, 질문 여부는 같은 입력에 항상 같은 결과를 내는 결정 규칙이 정합니다.

• 선택적 분석: 규칙과 경량 모델(Claude Haiku 5.5)로 위험도를 먼저 판단하여, 위험한 요청에만 정밀 분석을 수행합니다.

• 규칙 기반 안전 검사: "아까 그거"처럼 가리킬 수 있는 결과물이 여럿인데 하나로 확정한 경우, 언어모델과 독립된 규칙이 이를 질문으로 전환합니다.

아이디어 변경 과정

단계별 설계 변경의 배경은 ideas/에 정리하였습니다.

평가 방법과 결과

최종 평가에서는 MCP를 사용하지 않는 조건과 함께, 개발 과정에서 정리한 판단 기준을 프롬프트 지침 4줄로만 제공한 조건을 비교 대상으로 포함하였습니다.

• Final-120: 사용자에게 전달되는 최종 응답 평가 (120건, 사람 검수 반영)

• Decision-150: 작업 수행을 제외하고 진행/질문 판단만 평가 (150건)

• MCP V3는 두 평가 모두에서 Direct보다 높은 점수를 기록하였으며, 특히 문맥으로 대상을 확인할 수 있는 요청을 추가 질문 없이 처리하였습니다.

• 지침 4줄 조건도 유사한 성능을 보였습니다. 이는 개발 과정에서 정립한 판단 기준 자체가 성능의 핵심임을 보여줍니다.

데이터셋별 결과와 차트는 results/에 정리하였습니다.

저장소 구조

├─ src/                    분석 엔진
│  ├─ workflow.ts            분석 → 결정 → 질문/프롬프트 생성 흐름, 답변 반영
│  ├─ ambiguityAnalyzer.ts   언어모델 모호성 분석
│  ├─ decisionEngine.ts      진행/질문 결정 규칙
│  ├─ clarificationQuestionGenerator.ts · contextResolver.ts · types.ts
│  ├─ llm/                   언어모델 API 연결
│  └─ promptBuilder/         작업용 프롬프트 생성
├─ experimental/v3/        ★ 최종 V3 MCP 서버
│  ├─ server.ts              MCP 진입점 (analyze_prompt 도구)
│  ├─ selectiveWorkflow.ts   선택적 분석 흐름
│  ├─ riskRouter*.ts · lightRouter.ts · hybridRouter.ts   위험도 판단
│  ├─ guards.ts              규칙 기반 안전 검사
│  ├─ questionFormat.ts · toolDescription.ts   질문 문구와 도구 설명
│  └─ directGuidance.ts      판단 기준을 정리한 지침 4줄
├─ test/                   핵심 단위 테스트 (Vitest)
├─ results/                평가 결과 요약과 차트
├─ docs/                   최종보고서
├─ ideas/                  문제 정의와 설계 변경 기록
└─ assets/                 그림

experimental/v3/는 개발 당시의 폴더 구조를 그대로 유지한 것으로, 최종 V3 MCP 서버의 코드입니다.

실행 방법

npm install
npm test

API 호출 없이 결정 규칙, 분석 흐름, 문맥 처리, 프롬프트 생성에 대한 핵심 단위 테스트 63개가 실행됩니다.

MCP 서버 실행 (V3): .env에 ANTHROPIC_API_KEY를 설정한 뒤 실행합니다.

KPI_PIPELINE=v3 KPI_ROUTER_VERSION=0.2 KPI_ROUTER=hybrid KPI_LIGHT_MODEL=claude-haiku-5-5 npx tsx experimental/v3/server.ts

Claude Desktop 연결

Claude Desktop 설정의 개발자 메뉴에서 claude_desktop_config.json을 열고 아래 항목을 추가한 뒤, Desktop을 완전히 종료하고 다시 실행합니다. 경로는 저장소를 내려받은 위치로, API 키는 본인의 키로 바꿉니다.

{
  "mcpServers": {
    "korean-prompt-improver-v3": {
      "command": "node",
      "args": [
        "<저장소 경로>/node_modules/tsx/dist/cli.mjs",
        "<저장소 경로>/experimental/v3/server.ts"
      ],
      "env": {
        "ANTHROPIC_API_KEY": "<본인의 Anthropic API 키>",
        "KPI_PIPELINE": "v3",
        "KPI_ROUTER_VERSION": "0.2",
        "KPI_ROUTER": "hybrid",
        "KPI_LIGHT_MODEL": "claude-haiku-5-5"
      }
    }
  }
}

• 이 서버는 로컬(stdio) 서버이므로, URL을 입력하는 커넥터 추가 화면이 아니라 설정 파일로 등록합니다.

• 분석에 사용되는 API 비용은 입력한 Anthropic API 키로 청구되며, Claude 구독과는 별개입니다.

실제 사용 예시

Claude Desktop 채팅에서 연결을 확인한 결과입니다. 도구 사용 여부는 Claude가 판단하므로, 확실하게 사용하려면 요청에 도구 사용을 명시합니다.

사용자: korean-prompt-improver-v3의 analyze_prompt 도구로 먼저 분석한 뒤 처리해 줘. (발표 대본 → 예상 질문 → 발표 제목 후보를 차례로 작성한 상황에서) 아까 그거 좀 더 공식적인 말투로 바꿔줘.

Claude (analyze_prompt 사용): "아까 그거"은(는) 다음 중 무엇을 의미하나요?

1. 발표 제목 후보 2. 예상 질문 3. 발표 대본

사용자: 발표 대본

Claude (analyze_prompt 사용): 분석을 마쳤습니다. 바꿀 대상은 발표 대본으로 정해졌습니다.

MCP를 사용하지 않은 경우에는 두 가지 해석을 문장으로 설명하는 긴 답변이 생성되었으나, MCP를 사용한 경우에는 선택형 질문 하나로 대상을 확인하고 답변을 반영해 작업 대상을 확정하였습니다.

관련 문서

• results/ — 데이터셋 구성과 성능 차트

• ideas/ — 문제 정의와 설계 변경 배경

• docs/ — 최종보고서

사용 기술

TypeScript · Node.js · MCP SDK · Zod · Vitest · Anthropic API (Claude Sonnet 4.5, Claude Haiku 5.5)

V2-1 평가에는 공개 benchmark인 CLAMBER와 MuDoCo(CC BY-NC 4.0)를 바탕으로 한국어 작업 상황에 맞게 각색한 사례를 사용하였습니다.

라이선스

MIT License