# Alfred VoC Analysis MCP v0.1

Heum Alfred/DESK VoC facts를 CX intelligence로 변환하는 MCP 서버입니다. 구조는 명시적으로 **Fact → Analysis → Synthesis**로 분리됩니다.

## Architecture

- `fact.py`: DB/API adapter가 구현할 `FactRepository`; Fact에는 AI 해석을 저장하지 않습니다.
- `analysis.py`: overview, issue intelligence, CX concern, emerging signal, trend driver, resolution effect를 deterministic Python으로 계산합니다.
- `synthesis.py`: 상세 Report, Executive Brief, 개선 Planning Signal DTO를 조합합니다.
- `server.py`: FastMCP tool adapter. 분석 코어는 MCP나 외부 LLM에 의존하지 않습니다.

입력 스키마는 `FactRecord(extra="allow")`로 source 확장 필드를 보존합니다. 실제 DB 스키마를 변경하지 않으며 production DB/API 연결은 `FactRepository` adapter로 추가합니다.

## MCP tools

- `get_voc_overview`
- `analyze_issue_frequency`, `analyze_issue_severity`, `analyze_issue_persistence`
- `analyze_unresolved_issues`, `rerank_issue_priorities`, `compare_issue_portfolio`
- `analyze_customer_experience`
- `detect_emerging_signals`
- `analyze_voc_trends`
- `analyze_resolution_effect`
- `build_report_dataset`, `build_executive_brief`, `build_improvement_signals`

Issue tools intentionally share one portfolio assessment so Frequency alone cannot contradict Priority Movement. Each issue result returns evidence, reason and confidence.

## Run

```bash
python -m venv .venv
pip install -e ".[dev]"
pytest
alfred-voc-analysis-mcp
```

v0.1 ships an in-memory reference adapter. Embed the service and call `configure_records`, or implement `FactRepository` for voc-management DB/API.

## Calibration

`AnalysisConfig` contains data-sufficiency and observation-window settings. Defaults are conservative technical defaults, not Heum policy. No opaque weighted score or fixed “N건=High” business rule is used.