# PATHWAY Diagnostic MCP

가설 기반 조직진단 엔진을 MCP 서버로 제공합니다. Claude Desktop 같은 MCP 클라이언트에 연결하면, 대화로 자료를 입력하고 정형화된 진단 결과(JSON)와 대시보드(HTML)를 받을 수 있습니다.

모든 계산은 사용자 PC에서 이뤄지며, 입력한 인사·재무 자료는 외부로 전송되지 않습니다. 별도 API 키는 필요하지 않습니다.

> 상태: v0.1 (1단계). 모든 결과는 **AI 초안**이며, 최종 판정은 전문가 검토(`record_review`)로 확정합니다.

## 진단 구조

| 계층 | 질문 | 방법 |
|---|---|---|
| 1. 성장·조직 상태 | 사업 성장단계에 조직 운영체계가 정합한가 | 15개 계량지표, 코호트 벤치마크, 8D 영역별 판정, 정합성 판정 |
| 2. 가설 기반 원인 | 관찰된 현상의 원인은 무엇인가 | 14개 패턴·62개 경쟁가설, 베이지안 갱신 + 몬테카를로 |
| 3. 의사결정·성과 | 무엇을 하고, 효과가 있었는가 | 개선과제 후보, 3·6·12·24개월 성과 기록 |

### 설계 원칙

- 지표가 기대범위를 벗어나도 **판정이 아니라 관찰 사실**로만 사용합니다.
- 8D 영역 점수를 **평균하지 않습니다**. 영역 간 단계가 2단계 이상 벌어지면 '혼재'로 두고 정합성은 '평가 보류'입니다.
- 가설 판정은 확률 하나가 아니라 **분포(5·50·95 백분위)** 로 냅니다. 분포 폭이 신뢰도가 됩니다.
- 가설 검증 전에는 조직개편·인력충원을 권고하지 않습니다. 실행 과제는 '전문가 검토로 원인 확정 시' 조건부입니다.
- 화면과 보고서에는 코드(B3, P07-H04) 대신 **한국어 표준 용어**만 씁니다. 코드는 데이터에 함께 보관합니다.

## 설치

Python 3.10 이상이 필요합니다.

```bash
pip install "pathway-diagnostic-mcp[benchmark] @ git+https://github.com/isyoon41/pathway-diagnostic-mcp"
# 또는 소스에서
pip install -e ".[benchmark]"
```

`[benchmark]`는 CatBoost 벤치마크 모델을 쓸 때만 필요합니다. 없으면 카탈로그의 코호트 표를 사용합니다.

### Claude Desktop 연결

`claude_desktop_config.json`에 추가합니다.

```json
{
  "mcpServers": {
    "pathway-diagnostic": {
      "command": "pathway-diagnostic-mcp",
      "env": {
        "PATHWAY_DB": "~/.pathway-diagnostic/diagnostic.db"
      }
    }
  }
}
```

| 환경변수 | 용도 | 기본값 |
|---|---|---|
| `PATHWAY_DB` | 사례·전문가 검토·성과 기록 DB | `~/.pathway-diagnostic/diagnostic.db` |
| `PATHWAY_MODEL_DIR` | 학습된 CatBoost 벤치마크 모델 폴더 | `~/.pathway-diagnostic/models` |
| `PATHWAY_CATALOG_DIR` | 비공개 카탈로그(증거 적합도·벤치마크 표 등) 폴더. 같은 이름 파일로 덮어씀 | 없음 |

## 사용 흐름

대화창에서 "이 회사 조직진단 해 줘"로 시작하면 Claude가 아래 순서로 도구를 호출하며 필요한 자료를 요청합니다.

| 순서 | 도구 | 하는 일 |
|---|---|---|
| 1 | `get_input_templates` | 입력 양식 안내 |
| 2 | `compute_metrics` | 15개 지표 산출. 자료가 없는 지표는 '평가 보류'와 이유 |
| 3 | `benchmark_metrics` | 동종 코호트 기대범위(P10·P50·P90)와 위치, 주요 요인 |
| 4 | `assess_stage` | 사업·조직 단계, 8D 영역 판정, 정합성과 신뢰도 |
| 5 | `screen_patterns` | 검토할 진단 패턴 후보 |
| 6 | `assess_hypotheses` | 패턴별 경쟁가설 사후확률 분포·판정 상태·지지/반박 근거 |
| 7 | `next_best_evidence` | 판정을 가장 크게 바꿀 추가 증거(인터뷰·자료요청 목록) |
| 8 | `recommend_actions` | 개선과제 후보와 성과 점검 시점 |
| 9 | `build_report` | 진단 결과 JSON + 오프라인 HTML 대시보드 |
| 10 | `save_case` · `record_review` · `record_outcome` · `get_case` | 사례 저장, 전문가 확정, 성과 추적 |

`get_catalog`로 패턴·가설·지표·증거 라이브러리·용어집·판정 기준을 조회할 수 있습니다.

### 정형 시작점 (MCP 프롬프트)

진단을 같은 순서로 시작할 수 있도록 프롬프트 4개를 제공합니다. Claude 데스크톱에서는 입력창의 **+** 메뉴, Claude Code에서는 `/mcp__pathway-diagnostic__<이름>`으로 부릅니다.

| 이름 | 제목 | 하는 일 | 입력값 |
|---|---|---|---|
| `start_diagnosis` | 조직진단 시작 | 자료 요청부터 보고서까지 전체 진단을 단계별로 진행 | 회사명, 산업 (선택) |
| `assess_cause` | 원인 가설 판정 | 인터뷰 메모를 증거로 분류해 한 패턴의 경쟁가설 판정 | 패턴 코드, 메모 |
| `interview_plan` | 다음 인터뷰 설계 | 판정을 가장 빨리 정리할 질문과 자료 요청 목록 작성 | 패턴 코드, 인터뷰 대상 |
| `record_expert_review` | 전문가 판정 확정 | 저장된 사례에 전문가 판정과 성과 기록 | 사례 ID (선택) |

### 입력 자료

| 자료 | 형식 | 필수 |
|---|---|---|
| 인원 명단 | CSV: `employee_id, department, position, manager_id, is_manager, is_ceo, hire_date, exit_date, fte, is_core_role, has_verified_backup` | 권장 |
| 재무 | 매출·전기 매출·영업이익·핵심 인건비(억원) | 권장 |
| 의사결정 기록 | CSV: `requested_date, decided_date, topic` | 선택 |
| 마일스톤 | CSV: `due_date, completed_date, title` | 선택 |
| 8D 영역 판단 | 영역별 조직단계·판정·신뢰도·근거 메모 | 정합성 판정 시 |
| 정성 관찰 | 인터뷰 메모 → 증거 ID·관찰 여부(present/absent)·근거 유형(FACT/ANALYSIS/STATEMENT) | 가설 판정 시 |

이름·주민번호 등 개인 식별정보는 넣지 마십시오. `employee_id`는 임의 코드로 충분합니다.

### 결과물

`build_report`는 `~/PathwayDiagnostic/reports/`에 두 파일을 만듭니다.

- `<회사>_<기준일>_diagnosis.json` — 결과 스키마 v1.0: `summary`, `metrics`, `d8`, `hypotheses`, `sensitivity`, `actions` 6개 묶음 + `meta`, `details`
- `<회사>_<기준일>_dashboard.html` — 인터넷 없이 열리는 1페이지 대시보드 (요약, 성장단계 매트릭스, 8D, 지표 벤치마크, 가설 판정, 추가 증거, 개선 로드맵)

## 샘플 실행

```bash
python examples/run_sample.py      # 가상의 '샘플 정밀부품 제조사 A'로 전체 흐름 실행
pytest                             # 단위 테스트 + MCP 프로토콜 종단 테스트
```

## 벤치마크 모델 학습 (CatBoost)

기업 단위 CSV(한 행 = 한 기업·한 회계연도)로 지표별 분위수 회귀 모델을 학습합니다.

```bash
python scripts/train_benchmark.py companies.csv \
  --targets REVENUE_PER_FTE,CORE_PEOPLE_COST_RATIO,HC_GROWTH \
  --features industry,listed,employees,company_age,revenue,revenue_growth \
  --cat industry,listed
```

모델이 있으면 서버가 자동으로 사용하고, 지표별 SHAP 상위 요인을 함께 돌려줍니다. 모델이 없으면 카탈로그의 코호트 표를 쓰며, 결과에 `uses_sample_benchmark`로 표시합니다.

## 카탈로그와 공개 범위

| 파일 | 내용 | 공개 버전 |
|---|---|---|
| `patterns.json` | 14개 패턴·62개 가설·8D 매핑 | 전체 |
| `metrics.json` | 15개 지표 정의(산식 v1.1) | 전체 |
| `terms_ko.json` | 한국어 표준 용어집 | 전체 |
| `rules.json` | 스크리닝·판정 기준·과제 템플릿 | 기본값 |
| `evidence_library.json` | 증거별 가설 적합도 | **P07·P11 초안만** |
| `benchmark_sample.json` | 코호트 기대범위 표 | **가상 샘플** |

나머지 패턴의 증거 적합도와 실제 벤치마크는 `PATHWAY_CATALOG_DIR`로 연결하는 비공개 카탈로그에서 제공하는 구조입니다.

## 알려진 한계

- 증거 적합도, 상태 판정 기준, 신뢰도 기준은 **전문가 초안 값이며 실증 검증 전**입니다.
- 공개 버전의 가설 판정은 P07·P11에서만 동작합니다. 다른 패턴은 비공개 카탈로그가 필요합니다.
- 사업 성장단계(B1~B4)의 증거 충족 기준이 확정되지 않아, 현재는 전문가가 입력한 단계를 사용합니다.
- 8D–패턴 매핑은 재구성안이며 공식 매핑표 확인이 필요합니다.

## 라이선스

Copyright 2026 isyoon41

[Apache License 2.0](LICENSE). 상업적 사용·수정·재배포가 가능하며, 재배포 시 라이선스 사본과 변경 사실을 함께 고지해야 합니다.

비공개 카탈로그(`PATHWAY_CATALOG_DIR`로 연결하는 증거 적합도·벤치마크)는 이 저장소에 포함되지 않으며 이 라이선스의 적용 대상이 아닙니다.