Skip to main content
Glama

korean-prompt-improver

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


개발 배경

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

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

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

Related MCP server: Kakao Map MCP Server

시스템 구조 (최종 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)로 위험도를 먼저 판단하여, 위험한 요청에만 정밀 분석을 수행합니다.

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

아이디어 변경 과정

단계

발견한 문제

적용한 방법

결과

V1 초기 구축

한국어 모호성의 분류와 처리 기준 정립

다섯 가지 모호성 유형, 결정 규칙, MCP 연동

Claude Desktop에서 분석 → 질문 → 답변 반영 → 프롬프트 생성 과정 확인. 실제 모델 평가에서 문맥으로 해소 가능한 요청에도 15건 질문

V2-1 최근 문맥

최근 대화와 오래된 대화를 같은 비중으로 판단, 긴 문서 뒷부분 미반영

최근 대상 우선 규칙, 문서 입력 4,000 → 12,000자

불필요한 질문 61.7% → 37.6%, 올바른 처리 51.7% → 70.6%

V2-2 질문 기준

해석이 여러 개 가능한 경우를 모두 질문 대상으로 판단

핵심 정보만 질문하고 주변 정보는 빈칸으로 처리, 분석 호출 통합

불필요한 질문 33.3% → 22.1%

V3 안정화

과거 지시 표현의 대상을 잘못 확정, 모든 요청에 정밀 분석 수행

규칙 기반 안전 검사, 선택적 분석, 질문 문구 개선

기존 실패 사례 3/3 교정, 40건 중 19건 분석 생략, 질문 길이 중앙값 103자 → 59자

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

평가 방법과 결과

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

비교 조건

내용

Direct

MCP 없이 언어모델이 요청을 직접 처리

Direct+지침

MCP 없이 판단 기준을 4줄의 지침으로 제공

MCP V3

개발한 MCP의 분석 결과를 언어모델이 활용

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

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

Direct

Direct+지침

MCP V3

Final-120 모호성 처리 점수

0.800

0.904

0.900

Decision-150 판단 정확도

80.0%

80.7%

86.0%

  • 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 서버
│  ├─ serverAuto.ts          MCP 진입점 (check_korean_ambiguity 도구, 자동 호출 지침 포함)
│  ├─ autoCall.ts            서버 지침과 도구 설명 (언제 호출할지)
│  ├─ server.ts              평가에 사용한 진입점 (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 호출 없이 결정 규칙, 분석 흐름, 문맥 처리, 프롬프트 생성, 자동 호출 지침에 대한 핵심 단위 테스트 69개가 실행됩니다.

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/serverAuto.ts

평가 결과를 재현할 때는 같은 분석을 쓰되 자동 호출 지침이 없는 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/serverAuto.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 구독과는 별개입니다.

  • 설정 파일은 Desktop을 완전히 종료한 상태에서 고칩니다. 실행 중에 고치면 Desktop이 종료될 때 이전 내용으로 덮어쓸 수 있습니다.

자동 호출: Claude Code와 Chat

이 서버는 "언제 호출할지"를 서버 지침과 도구 설명에 담아 보냅니다. 앞의 대상을 가리키는 말(그거, 아까 그거 등)이 있거나, 결과물이 여럿인데 대상을 생략했거나, 되돌리기 어려운 작업의 대상이 불분명하거나, 사용자만 아는 정보가 빠진 요청이면 Claude가 답하기 전에 먼저 도구를 호출합니다.

Claude Code

Chat (Claude Desktop·claude.ai)

서버 지침

전달됨

전달되지 않음

자동 호출

추가 설정 없이 작동

아래 Claude 지침을 추가하면 작동

Chat에서는 설정 → 계정 → Claude 지침에 아래 문구를 추가합니다. 새 대화부터 적용됩니다.

[한국어 모호성 확인] 한국어 요청이 아래 중 하나에 해당하면, 모호한지 직접 판단하지 말고 작업 전에 korean-prompt-improver-v3의 check_korean_ambiguity를 먼저 호출하고, 질문이 나오면 요약하거나 설명을 덧붙이지 말고 그대로 보여 줄 것.
- 앞의 대상을 가리키는 말이 있을 때: 그거, 이거, 저거, 아까 거, 위에 거, 그분, 거기, 그때, 그 파일, 그 메일
- 대상을 생략했는데 앞 대화에 결과물이 둘 이상일 때 (예: 제목 후보와 대본을 만든 뒤 "더 짧게 해 줘")
- 삭제·발송·해지·덮어쓰기·결제처럼 되돌리기 어려운 작업인데 대상을 이름으로 밝히지 않았을 때 (예: "그 메일 보내 줘")
- 결과의 핵심이 사용자만 아는 사실인데 주어지지 않았을 때: 개인 경험, 실제 수치, 날짜, 장소, 분량 기준 (예: "내 지원 동기 써 줘")
단, 앞 대화를 가리키지 않는 새 요청이나 대상을 이름·번호·"전부"로 집은 요청은 호출하지 않는다.

커넥터 권한을 "항상 허용"으로 두면 호출할 때마다 확인 창이 뜨지 않습니다. 호출 여부는 최종적으로 Claude가 정하므로, 꼭 확인이 필요한 요청에는 도구 이름을 함께 적습니다.

실제 사용 예시

Claude Desktop 채팅에서 도구 사용을 요청에 명시해 연결을 확인한 결과입니다.

사용자: 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

Available Tools

1 tool
analyze_prompt한국어 프롬프트 모호성 분석 및 개선 (V3 실험)B

사용자의 짧고 모호한 한국어 요청을 이전 대화와 첨부 문서 문맥으로 분석해 모호성을 해결하고, 필요한 경우에만 명확화 질문을 반환하며, 그렇지 않으면 실제 작업에 사용할 수 있는 개선된 Prompt를 생성한다.

Inputs: current_user_request (required), answers, task_hint, document_context, +2 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 1 tool

    Disambiguation5/5

    The server exposes only one tool, so there is no risk of selecting between overlapping operations. Its purpose—analyzing and improving Korean prompts—is clear and distinct.

    Naming Consistency5/5

    The single tool name analyze_prompt follows a clear verb_noun snake_case convention. There are no mixed naming styles or inconsistencies to evaluate.

    Tool Count4/5

    This is a narrowly scoped single-purpose server, so one tool is reasonable and avoids unnecessary surface area. It is minimal, but not obviously mismatched to the task.

    Completeness4/5

    The tool covers the core workflow: ambiguity analysis using context, optional clarification questions, and generation of an improved prompt. A separate refinement or follow-up tool is absent, but the same tool can likely be re-invoked with added context.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • -
      license
      Not graded
      quality
      Not graded
      maintenance
      Enables users to generate and execute InfluxDB queries using natural language commands in Korean. Supports querying metrics like CPU usage, memory status, and system monitoring data through conversational interface.
      -
    • A
      license
      A
      quality
      D
      maintenance
      Provides location-based place recommendations in South Korea using the Kakao Map API, optimized for Korean language queries. Supports recommending various places like restaurants, shops, public facilities, and tourist attractions based on user queries.
      1
      16
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Analyzes ambiguous Korean chat messages by interpreting nuance, emotional tone, and context, and suggests appropriate replies for social situations like apology, refusal, or setting boundaries.
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      Helps users prepare Korean neighborhood inconvenience reports by classifying issues, explaining evidence, and drafting neutral reports without submitting them.
      -