korean-prompt-improver
This MCP server analyzes short or ambiguous Korean requests and either asks only necessary clarification questions or returns an improved task-ready prompt.
Accepts the current Korean request plus recent conversation, document context, prior analysis, answers, and a task hint.
Detects when ambiguity can be resolved from context versus when user confirmation is needed.
Asks concise clarification questions for unclear targets, multiple possible referents, risky/irreversible actions, or missing user-only information.
Incorporates clarification answers and generates a refined prompt for actual task execution.
Integrates with Claude Desktop/Code/Chat as an MCP tool and supports automatic-call guidance.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@korean-prompt-improver 아까 그 발표 대본 좀 더 공식적인 말투로 다듬어 줘"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 testAPI 호출 없이 결정 규칙, 분석 흐름, 문맥 처리, 프롬프트 생성, 자동 호출 지침에 대한 핵심 단위 테스트 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 사용): "아까 그거"은(는) 다음 중 무엇을 의미하나요?
발표 제목 후보 2. 예상 질문 3. 발표 대본
사용자: 발표 대본
Claude (analyze_prompt 사용): 분석을 마쳤습니다. 바꿀 대상은 발표 대본으로 정해졌습니다.
MCP를 사용하지 않은 경우에는 두 가지 해석을 문장으로 설명하는 긴 답변이 생성되었으나, MCP를 사용한 경우에는 선택형 질문 하나로 대상을 확인하고 답변을 반영해 작업 대상을 확정하였습니다.
관련 문서
사용 기술
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)를 바탕으로 한국어 작업 상황에 맞게 각색한 사례를 사용하였습니다.
라이선스
Available Tools
1 toolanalyze_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
Scored across 1 tool
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.
The single tool name analyze_prompt follows a clear verb_noun snake_case convention. There are no mixed naming styles or inconsistencies to evaluate.
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.
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
Related MCP Connectors
Turns rough requests into sharp Role/Task/Context/Format prompts. Thai and English.
Turn a rough request into a specialized prompt using your saved profile and business context.
Turns vague automation requests into tool stacks, prompts, QA checks, and human boundaries.
Find your AI agent's likely failure mode, get runtime settings, and clarify ambiguous prompts.
Related MCP Servers
- -licenseNot gradedqualityNot gradedmaintenanceEnables 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.-
- AlicenseAqualityDmaintenanceProvides 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.116MIT
- AlicenseNot gradedqualityCmaintenanceAnalyzes 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
- FlicenseNot gradedqualityDmaintenanceHelps users prepare Korean neighborhood inconvenience reports by classifying issues, explaining evidence, and drafting neutral reports without submitting them.-