mcp-probe-kit

말은 쉽습니다, 컨텍스트(Context)를 보여주세요. mcp-probe-kit는 AI가 프로젝트의 의도를 진정으로 이해하기를 원하는 개발자들을 위해 설계된 프로토콜 레벨(protocol-level)의 툴킷입니다. 이는 단순히 30개의 도구 모음이 아닙니다. AI 에이전트가 당신이 무엇을 만들고 있는지 파악하도록 돕는 컨텍스트 인식(context-aware) 시스템입니다.

🚀 AI 기반의 완전한 개발 툴킷 - 전체 개발 라이프사이클(Development Lifecycle)을 아우름

제품 분석부터 최종 출시(요구사항 → 설계 → 개발 → 품질 → 출시)까지의 전체 워크플로우를 다루는 30개의 도구를 제공하는 강력한 MCP (Model Context Protocol) 서버입니다. 모든 도구는 **구조화된 출력 (structured output)**을 지원합니다.

🎉 v3.0 주요 업데이트: 도구 수를 간소화하고 핵심 역량에 집중하여, 선택 장애를 제거하고 AI가 더 많은 네이티브 작업을 수행할 수 있도록 함

모든 MCP 클라이언트 지원: Cursor, Claude Desktop, Cline, Continue 등

프로토콜 버전: MCP 2025-11-25 · SDK: @modelcontextprotocol/sdk 1.27.1

빠른 시작 (Quick Start) - 5분 만에 설정
로컬 메모리 스택 (Local Memory Stack) (Qdrant + Nomic Embed) - Docker Compose, 포트 50008, 50012, MCP 환경 - 모든 도구 - 30개 도구 전체 목록
베스트 프랙티스 (Best Practices) - 전체 개발 워크플로우 가이드
v3.0 마이그레이션 가이드 (v3.0 Migration Guide) - v2.x에서 v3.0으로 업그레이드

🔄 워크플로우 오케스트레이션 (Workflow Orchestration) (6개 도구) - 클릭 한 번으로 복잡한 개발 워크플로우 실행 start_feature, start_bugfix, start_onboard, start_ui, start_product, start_ralph

🔍 코드 분석 (Code Analysis) (4개 도구) - 코드 품질, 리팩토링 및 그래프 통찰력 code_review, code_insight, fix_bug, refactor

📝 Git 도구 (Git Tools) (2개 도구) - Git 커밋 및 작업 보고서 gencommit, git_work_report

⚡ 코드 생성 (Code Generation) (1개 도구) - 테스트 생성 gentest

📦 프로젝트 관리 (Project Management) (7개 도구) - 프로젝트 초기화, 요구사항 및 사양 검증 init_project, init_project_context, add_feature, check_spec, estimate, interview, `ask_user"

🎨 UI/UX Utilities(3개 도구) - 디자인 시스템 및 UI 데이터 동기화 ui_design_system, ui_search, sync_ui_data

🧠 Memory(6개 도구) - 재사용 가능한 자산 메모리 search_memory, read_memory_asset, memorize_asset, update_memory_asset, delete_memory_asset, scan_and_extract_patterns

모든 엄격한 품질 규칙(hard quality rules)은 하나의 모듈(src/lib/quality-constraints.ts)에 상주하며, code_review, add_feature 작업 템플릿, 그리고 UI 도구들에 주입됩니다. 한 번의 변경으로 모든 곳에 적용됩니다 — 이는 taste-skill 및 impeccable에서 영감을 받았습니다.

코드 제한(Code limits): 단일 파일 ≤ 500행 (초과 시 모듈/컴포넌트로 분할), 함수 ≤ 50행, 중첩(nesting) ≤ 4단계, 파라미터(parameters) ≤ 3개.

완결성 블랙리스트(Completeness blacklist): code_review는 플레이스홀더/생략 패턴(// ..., // TODO, // rest of code, 단독 ...)을 CRITICAL(심각)로 표시합니다 — "부분적인 출력은 망가진 출력이다"라는 원칙을 따릅니다.

안티-게으름 작업 템플릿(Anti-laziness task templates): add_feature 작업에는 이제 Scope-lock 산출물 개수, 필수 증거 블록(작성 전 코드 읽기), 파일당 라인 예산, 그리고 플레이스홀더에 대한 이진 제로-톨러런스(binary zero-tolerance) 규칙이 포함됩니다. check_spec은 이를 검증합니다 (Scope-lock 누락 = 에러, 증거 없는 빈약한 작업 = 경고).

UI 엄격한 레드라인(UI hard red lines): 수치적이고 기계적으로 확인 가능한 규칙들 — 4pt 간격 스케일, WCAG 대비(4.5/3/3), 타이포그래피 스케일(type scale) ≥ 1.25, 히어로 폰트(hero font) ≤ 6rem, OKLCH, 8가지 상호작용 상태, 인지 부하(cognitive load) ≤ 4, 모션 150-300ms.

UI 금지 목록 + 프리플라이트 체크리스트(UI banned list + Pre-Flight checklist): AI 슬롭(AI slop)을 방지하기 위한 매치 앤 리퓨즈(match-and-refuse) 블랙리스트 (기본 Inter/Roboto, AI 퍼플-블루 그라데이션, 그라데이션 텍스트, 정형화된 카드 그리드, em-dash, 크림/베이지색 본문 배경, 중첩된 카드) 및 인도 게이트(delivery-gate) 셀프 체크 매트릭스.

code_insight는 쿼리/컨텍스트/영향 분석을 위해 기본적으로 GitNexus를 연결합니다 — 이 브릿지는 오래된 패키지 위험을 줄이기 위해 기본적으로 npx -y gitnexus@latest mcp를 실행합니다. init_project_context는 docs/graph-insights/ 아래에 기본 그래프 문서를 부트스트랩합니다; 만약 docs/project-context.md

이미 존재한다면, 기존의 컨텍스트 문서를 보존하고 그래프 문서와 인덱스 항목만 백필(backfill)합니다.start_feature

GitNexus 인덱스를 새로고침하고, 사양(spec) 생성 전 범위 초과(over-scoping)를 줄이기 위해 태스크 수준의 query/context/impact를 실행하여 범위를 좁힙니다.start_bugfix

TBP RCA(근본 원인 분석) 전에 GitNexus 인덱스를 새로고침하고 태스크 수준의 그래프 분석을 실행하여 실패 경계(failure boundary)와 영향 범위(blast radius)를 제한합니다. - project-context.md는 이미 존재하지만 그래프 문서가 없는 오래된 프로젝트는 init_project_context 단계를 통해 자동으로 부트스트랩(bootstrap)됩니다.

GitNexus를 사용할 수 없는 경우, 서버는 오케스트레이션(orchestration)을 중단하지 않고 자동으로 폴백(fallback)합니다.
실제 그래프 쿼리는 .gitnexus 인덱스를 읽습니다. docs/graph-insights/latest.md|json은 인간과 AI 에이전트가 읽을 수 있는 스냅샷입니다. MCP 클라이언트 설정 목록의 MCP 리소스에는 2개의 항목(probe://status, probe://project/bootstrap)이 있습니다. 그래프 런타임 스냅샷(probe://graph/latest 등)과 probe://project/skill|agents|context|graph는 도구가 URI를 노출할 때 resources/read를 통해 읽기 가능한 상태로 유지됩니다. - 그래프 스냅샷은 .mcp-probe-kit/graph-snapshots에 저장됩니다 (MCP_GRAPH_SNAPSHOT_DIR를 통해 사용자 정의 가능). - 도구 응답에는 스냅샷 URI와 로컬 JSON/Markdown 파일 경로가 포함된 _meta.graph가 포함됩니다.

start_bugfix는 수정(fix_bug) 전에 Toyota 스타일의 TBP 8단계 근본 원인 분석(root-cause analysis)을 기본값으로 수행합니다. fix_bug는 현상, 타임라인, 제외된 경로, 경계, 근본 원인, 증거 및 수정 계획을 다루는 구조화된 TBP 스켈레톤(skeleton)을 반환합니다. - 이를 통해 버그, 회귀(regression), 이상 징후 및 "왜 작동하지 않았는가"에 대한 조사가 증상을 임시로 패치하는 대신 "선 분석 후 조치(analyze-first)" 원칙을 따르게 합니다.

메모리 도구는 벡터 데이터베이스 백엔드로 Qdrant를 사용합니다. - 임베딩(Embedding) 서비스는 두 가지 모드를 지원합니다: ollama, openai-compatible.

메모리 도구:

search_memory

공유 메모리 풀 전체에 대한 시맨틱 검색(semantic search) (type/tags를 선택적으로 선호할 수 있음); 텍스트 출력에는 id, score, 요약, 설명 및 --- content ---가 포함됩니다.

body (기본값은 MEMORY_SEARCH_CONTENT_MAX_CHARS를 통해 최대 1500자까지 가능)

memorize_asset

재사용 가능한 코드/명세(spec)/패턴 자산을 벡터 메모리(vector memory)에 영구 저장

read_memory_asset

asset_id를 통해 전체 자산 콘텐츠를 읽기 (텍스트 출력에는 전체 content body가 포함됨)

update_memory_asset

asset_id를 통해 기존 자산을 업데이트 (ID는 유지되며, content 변경 시 재임베딩(re-embed) 수행)

delete_memory_asset

공유 풀(shared pool)에서 asset_id를 통해 자산 삭제

scan_and_extract_patterns

영구 저장 여부를 결정하기 전에 코드/파일/디렉토리에서 재사용 가능한 패턴을 추출

교차 리포지토리 메모리 풀 (Cross-repo memory pools): 공유 검색을 위해 source_project / source_path에 의존하지 마세요. 대신 content에 파일 경로를 넣으세요. 검색 주입(Search injection)은 MEMORY_REPO_ID가 일치하거나 MEMORY_SEARCH_SHOW_SOURCE=true인 경우가 아니면 외부 sourcePath를 숨깁니다.

메모리 백엔드 및 임베딩 설정 (Memory backend and embedding configuration):

벡터 데이터베이스 (Vector database):
Qdrant
권장 로컬 설정: Qdrant (port 50008) + Infinity / nomic-embed (port 50012)
— Ollama보다 가볍습니다; Local Memory Stack 가이드(중문: memory-local-setup.zh-CN.md)를 참조하세요.
지원되는 임베딩 제공자 (Supported embedding providers):
ollama
openai-compatible (Infinity, OpenAI 등)
메모리 쓰기/검색을 위한 필수 환경 변수 (Required environment variables for memory write/search):
MEMORY_QDRANT_URL
MEMORY_EMBEDDING_URL
MEMORY_EMBEDDING_MODEL
선택적 환경 변수 (Optional environment variables):
MEMORY_QDRANT_API_KEY
MEMORY_QDRANT_COLLECTION (기본값: mcp_probe_memory)
MEMORY_EMBEDDING_API_KEY
MEMORY_EMBEDDING_PROVIDER (ollama가 기본값)
MEMORY_SEARCH_LIMIT (기본값: 3)
MEMORY_SUMMARY_MAX_CHARS (기본값: 280)
MEMORY_SEARCH_MIN_SCORE (기본값: 0 = 비활성화; 노이즈가 많은 풀의 경우 0.72 시도)
MEMORY_SEARCH_SHOW_SOURCE (기본값: false)
MEMORY_REPO_ID (선택 사항; sourceProject가 일치할 때만 sourcePath를 표시)
MEMORY_INJECTION_CONTENT_MAX_CHARS (기본값: 1500; start_* 가이드에 주입되는 검색 결과당 최대 콘텐츠 양)
동작 참고 사항 (Behavior notes):
읽기 전용 메모리 액세스에는 MEMORY_QDRANT_URL만 필요합니다.
메모리 쓰기 (Memory write)는 MEMORY_QDRANT_URL, MEMORY_EMBEDDING_URL, 그리고 MEMORY_EMBEDDING_MODEL이 모두 설정된 경우에만 활성화됩니다. - Qdrant 컬렉션은 첫 번째 쓰기 시 자동으로 생성되며, 벡터 차원 (vector dimension)은 첫 번째 임베딩 (embedding) 응답으로부터 추론됩니다.
읽기 전용 메모리 액세스에는 MEMORY_QDRANT_URL만 필요합니다.

권장되는 로컬 메모리 설정 (Qdrant + Nomic Embed / Infinity):

전체 Docker Compose, 포트 및 문제 해결: docs/memory-local-setup.md

{
"mcpServers": {
"mcp-probe-kit": {
...

대안: Qdrant + Ollama (이미 Ollama를 실행 중인 경우):

docker run -d --name mcp-qdrant -p 6333:6333 qdrant/qdrant
ollama pull nomic-embed-text

"MEMORY_QDRANT_URL": "http://127.0.0.1:6333",
"MEMORY_EMBEDDING_PROVIDER": "ollama",
"MEMORY_EMBEDDING_URL": "http://127.0.0.1:11434/api/embeddings",
...

OpenAI 호환 임베딩 (호스팅 API):

{
"mcpServers": {
"mcp-probe-kit": {
...

코어 및 오케스트레이션 (orchestration) 도구는 **구조화된 출력 (structured output)**을 지원하여, 기계가 읽을 수 있는 JSON 데이터를 반환함으로써 AI 파싱 (parsing) 정확도를 높이고, 도구 체이닝 (tool chaining) 및 상태 추적 (state tracking)을 지원합니다.

MCP SDK의 네이티브 태스크 지원 (taskStore + taskMessageQueue)을 기반으로 구축되었습니다. - 태스크 생명주기 엔드포인트 (task lifecycle endpoints)를 지원합니다: tasks/get, tasks/result, tasks/list, tasks/cancel
클라이언트가 tools/call을 위한 태스크를 생성할 수 있도록 capabilities.tasks.requests.tools.call을 광고 (advertises)합니다.
클라이언트가 _meta.progressToken을 제공할 때 notifications/progress를 방출 (emits)합니다.
AbortSignal을 통해 요청 취소를 처리하고 명확한 취소 에러를 반환합니다. - 장시간 실행되는 오케스트레이션 도구 (start_*) 및 sync_ui_data는 협력적 취소/진행 콜백 (cooperative cancellation/progress callbacks)을 지원합니다.
트레이스 메타데이터 전달 (Trace metadata passthrough): 요청 _meta.trace는 도구 응답 (_meta.trace)에 보존됩니다. - 선택적 확장 기능 (optional extensions capability) 스위치: MCP_ENABLE_EXTENSIONS_CAPABILITY=1로 활성화합니다.
UI 도구를 위한 선택적 MCP Apps 리소스 출력: MCP_ENABLE_UI_APPS=1로 활성화합니다.
UI 도구는 ui://...를 통해 프리뷰 리소스를 노출할 수 있습니다.

및 응답의 _meta.ui.resourceUri

모든 start_* 오케스트레이션 도구(orchestration tools)는 structuredContent.metadata.plan에 **실행 계획 (execution plan)**을 반환합니다.

AI는 도구가 내부적으로 실행되도록 하는 대신, **단계별로 도구를 호출하고 파일을 유지(persist)**해야 합니다.

계획 스키마 (Plan Schema - 핵심 필드):

{
"mode": "delegated",
"steps": [
...

필드 설명:

mode
: delegated로 고정

steps
: 실행 단계(execution steps)의 배열

tool
: 도구 이름 (예: add_feature)

action
: 도구가 없는 경우의 수동 작업 설명 (예: update_project_context)

args
: 도구 파라미터 (tool parameters)

outputs
: 예상 결과물 (expected artifacts)

when/dependsOn/note
: 선택적 조건 및 참고 사항

오케스트레이션 도구와 원자적 도구(atomic tools) 모두 structuredContent를 반환하며, 공통 필드는 다음과 같습니다:

summary
: 한 줄 요약

status
: 상태 (pending/success/failed/partial)

steps
: 실행 단계 (오케스트레이션 도구)

artifacts
: 결과물 목록 (경로 + 용도)

metadata.plan
: 위임된 실행 계획 (start_* 도구 전용)

specArtifacts
: 명세 결과물 (start_feature)

estimate
: 추정 결과 (start_feature / estimate)

요구사항이 불분명할 경우, start_feature / start_bugfix / start_ui에서 requirements_mode=loop를 사용하십시오.

이 모드는 명세(spec)/수정(fix)/UI 실행 단계로 진입하기 전에 1~2라운드의 구조화된 명확화(clarification) 과정을 수행합니다.

예시:

{
"feature_name": "user-auth",
"description": "User authentication feature",
...

add_feature는 템플릿 프로필(template profiles)을 지원하며, 기본값은 auto입니다.

auto는 다음과 같이 자동 선택합니다:

요구사항이 불완전할 때: guided를 선호합니다 (상세한 작성 규칙 및 체크리스트 포함).
요구사항이 완전할 때: strict를 선택합니다 (더 압축된 구조로, 고성능 모델이나 아카이브 시나리오에 적합).

예시:

{
"description": "Add user authentication feature",
"template_profile": "auto"
...

적용 가능한 도구:

start_feature는 template_profile을 add_feature로 전달합니다.
start_bugfix / start_ui 또한 template_profile을 지원합니다.

가이드 강도(guidance strength)를 제어하기 위한 설정 (auto/guided/strict)

템플릿 프로필 전략 (Template Profile Strategy):

guided
: 요구사항 정보가 적거나 불완전할 때 사용하며, 일반적인 모델 우선순위를 따름

strict
: 요구사항이 구조화되어 있을 때 사용하며, 더 압축된 가이드를 선호함

auto
: 기본 권장 사항으로, guided 또는 strict를 자동으로 선택함

하나의 복잡한 개발 워크플로우를 원클릭으로 수행하기 위해 여러 기본 도구들을 자동으로 결합하는 6가지 지능형 오케스트레이션(orchestration) 도구:

start_feature

새로운 기능 개발 (요구사항 → 설계 → 추정)

start_bugfix

버그 수정 (TBP 8단계 RCA → 수정 → 테스트)

start_onboard

프로젝트 온보딩 (프로젝트 컨텍스트 문서 생성)

start_ui

UI 개발 (디자인 시스템 → 컴포넌트 → 코드)

start_product

mcp-probe-kit

요약

핵심 포인트

댓글