# MendLens

> **See what's wrong. Know what to do.**

![MendLens 대표 이미지](assets/mendlens-mcp-representative.png)

**MendLens(찍고쳐)** 는 가전제품 사진이나 오류 코드를 바탕으로 공식 설명서와 리콜 정보를 확인하고, 사용자가 지금 취해야 할 행동을 안내하는 생활 수리 AI 에이전트다.

## 한 줄 소개

버리기 전에 찍어보세요. 공식 정보로 안전하게 고쳐드립니다.

## 해결하려는 문제

가전제품에 오류가 발생하면 사용자는 원인을 찾기 위해 모델명, 설명서, 오류 코드, 리콜 여부를 각각 검색해야 한다. 검색 결과가 정확한 제품의 공식 정보인지 판단하기도 어렵다.

MendLens는 이 과정을 하나의 대화로 줄인다. 사용자가 제품 사진이나 오류 코드를 보내면 제품과 모델을 식별하고 공식 근거를 조회해 다음 세 가지 중 하나로 판단한다.

- 즉시 사용 중단
- 직접 해결 가능
- 공식 AS 필요

## 핵심 사용자 경험

사용자가 카카오톡에서 세탁기의 `UE` 오류 화면을 촬영하고 묻는다.

> 이거 왜 이래?

MendLens는 한 번에 다음 정보를 제공한다.

1. 확인된 제품과 모델
2. 공식 설명서에 따른 오류 원인
3. 사용자가 시도할 수 있는 해결 절차
4. 즉시 사용을 중단해야 하는 위험 조건
5. 리콜 여부와 공식 AS 연결

제품이나 모델을 확실히 식별하지 못한 경우에는 추측으로 진단하지 않고 추가 사진이나 모델명을 요청한다.

## MVP 범위

초기 버전은 오류 코드가 비교적 명확하고 일상에서 자주 사용하는 다음 생활가전에 집중한다.

- 세탁기
- 에어컨
- 냉장고
- 식기세척기
- 로봇청소기

모든 제품을 넓게 지원하기보다, 제한된 제품군에서 공식 근거와 안전한 행동 지침을 안정적으로 제공하는 것을 우선한다.

## 핵심 가치

- **편의성:** 사진 한 장이나 오류 코드만으로 탐색 과정을 시작한다.
- **정확성:** 일반적인 추측보다 모델별 공식 설명서와 공공 데이터를 우선한다.
- **안전성:** 자가 조치가 위험한 상황을 구분하고 즉시 사용 중단 또는 AS를 안내한다.
- **경제성:** 사용자가 해결할 수 있는 단순 문제로 불필요한 출장 수리나 제품 교체를 줄인다.
- **환경성:** 수리 가능한 제품의 조기 폐기를 줄인다.

## 공식 데이터 후보

- 제조사별 공식 제품 설명서, 오류 코드 및 AS 정보
- [제품안전정보센터 Open API](https://www.safetykorea.kr/release/openapi): KC 인증 정보, 국내 리콜 정보, 국외 리콜 정보

제조사별 설명서의 제공 방식, 이용 조건, 자동 조회 가능 여부는 구현 전에 별도로 확인해야 한다.

## 공모전 적합성

이 프로젝트는 카카오 **AGENTIC PLAYER 10** 출품 아이디어에서 시작했다. 공모전의 공식 평가 기준과 MendLens의 대응 방향은 다음과 같다.

| 평가 기준 | MendLens의 대응 |
| --- | --- |
| 창의성 | 사진과 공식 제품 정보를 결합해 고장 진단 이후의 행동까지 연결한다. |
| 편의성 | 카카오톡 대화에서 사진을 보내고 즉시 결과를 받는다. |
| 안정성 | 공식 근거를 우선하고 제품 식별 실패와 위험 상황에서는 진단 범위를 제한한다. |

본선은 내부 심사와 Kakao Tools 사용자 투표를 함께 반영하므로, 첫 사용에서 가치가 드러나는 짧은 흐름과 가족에게 공유하기 쉬운 결과 형식이 중요하다.

공식 안내: [AGENTIC PLAYER 10](https://b.kakao.com/views/PlayMCP/AGENTIC_PlAYER_10)

## 이름과 브랜드

- **영문명:** MendLens
- **한글명:** 찍고쳐
- **표기:** 찍고쳐 | MendLens
- **태그라인:** See what's wrong. Know what to do.

`Mend`는 고치고 수선한다는 의미를, `Lens`는 사진으로 문제를 발견한다는 경험을 나타낸다. 정식 출시 전에는 상표와 서비스명 사용 가능 여부를 별도로 확인해야 한다.

## 성공 기준

MVP는 다음 조건을 충족할 때 성공으로 본다.

- 지원 제품군에서 제품 또는 모델을 식별할 수 있다.
- 답변에 공식 정보의 출처를 제시한다.
- 직접 해결, AS 필요, 즉시 사용 중단을 명확히 구분한다.
- 확신할 수 없는 경우 추측하지 않고 필요한 추가 정보를 요청한다.
- 대표 데모 시나리오를 카카오톡 안에서 짧고 자연스럽게 완료한다.

## 아직 결정하거나 검증할 사항

- 지원할 제조사와 모델의 우선순위
- 제품 및 모델 식별 방식과 정확도 기준
- 제조사 설명서 수집·검색 방식과 이용 조건
- 안전 판단 규칙과 책임 고지 범위
- PlayMCP 도구 인터페이스와 Kakao Tools 결과 UI
- 개인정보 및 사용자 이미지 보관 정책
- MendLens와 찍고쳐의 상표·도메인 사용 가능 여부

## 대회 일정 메모

공식 페이지에 게시된 일정 기준으로 예선 접수 마감은 **2026년 7월 14일**이며, PlayMCP 서버 심사는 영업일 기준 최대 7일이 소요될 수 있다. 참가에는 카카오클라우드 MCP 서버 생성, PlayMCP 등록 및 심사, 전체 공개 전환, 예선 접수가 요구된다. 일정과 제출 상태는 반드시 [공식 페이지](https://b.kakao.com/views/PlayMCP/AGENTIC_PlAYER_10)에서 다시 확인한다.

## 현재 MCP 구현

현재 버전은 Endpoint와 PlayMCP 흐름을 검증하기 위한 제한된 MVP다. 실시간 제조사 검색이나 리콜 조회를 지원한다고 주장하지 않으며, 2026년 7월 14일에 공식 근거를 확인한 다음 사례만 진단한다.

| 제조사 | 제품 | 모델 | 코드 | 최종 행동 |
| --- | --- | --- | --- | --- |
| LG전자 | 통돌이 세탁기 | T1204T | UE | 직접 해결 가능 |
| LG전자 | 드럼세탁기 | F8Q6CNVKQ | UE | 직접 해결 가능 |
| LG전자 | 스탠드형 에어컨 | FQ19V9KWAN | CH05 | 공식 AS 필요 |

제공 도구는 다음 세 개다.

- `prepare_diagnosis`: 진단에 필요한 제조사·제품군·모델·오류 코드의 누락 여부 확인
- `diagnose_error_code`: 정확히 일치하는 공식 근거가 있을 때만 오류 진단 반환
- `assess_immediate_risk`: 명시적인 위험 신호를 자가 조치보다 먼저 분류

## 로컬 실행

요구사항은 Node.js 22 이상이다.

```bash
npm install
npm test
npm run build
npm start
```

기본 주소는 `http://127.0.0.1:3000`이며 MCP 경로는 `/mcp`, 상태 확인 경로는 `/health`다.

```bash
npm run smoke -- http://127.0.0.1:3000
npm run benchmark -- http://127.0.0.1:3000 100
```

## Docker 검증

```bash
docker build --platform linux/amd64 -t mendlens-mcp:local .
docker run --rm --platform linux/amd64 -p 3000:3000 mendlens-mcp:local
```

컨테이너는 `PORT` 환경 변수를 사용하고 non-root `node` 사용자로 실행된다.

2026년 7월 14일 로컬 Docker Desktop에서 `linux/amd64` 컨테이너의 `diagnose_error_code`를 10회 예열 후 100회 순차 호출한 측정값은 평균 `2.77ms`, p99 `7.56ms`였다. 이 값은 로컬 환경 측정치이며 PlayMCP in KC의 production 성능을 보장하지 않는다.

## PlayMCP in KC Git 소스 빌드

- MCP 서버 이름: `mendlens`
- 설명: `공식 제조사 근거에 일치하는 가전 오류 진단과 안전 행동을 제공하는 MendLens MCP 서버`
- 브랜치/ref: `ps/feat/mendlens-mcp-server`
- Dockerfile 경로: `Dockerfile`
- 컨테이너 포트: `3000`
- PAT: public 저장소이므로 입력하지 않음

2026년 7월 14일 배포 상태는 `Active`이며, 발급된 Endpoint는 다음과 같다.

```text
https://mendlens.playmcp-endpoint.kakaocloud.io/mcp
```

공개 Endpoint의 헬스체크, MCP 초기화, 도구 목록과 대표 호출 smoke test가 통과했다. 동일 Endpoint에서 `diagnose_error_code`를 10회 예열 후 100회 순차 호출한 측정값은 평균 `41.49ms`, p99 `52.48ms`였다.

다음 명령으로 현재 배포 상태를 다시 확인할 수 있다.

```bash
npm run smoke -- https://mendlens.playmcp-endpoint.kakaocloud.io/mcp
npm run benchmark -- https://mendlens.playmcp-endpoint.kakaocloud.io/mcp 100
```

공식 근거와 제출 절차의 확인 기록은 [PlayMCP · AGENTIC PLAYER 10 조사 문서](docs/research/playmcp-agentic-player-10.md)에 유지한다.