mcp-gwansang

관상(觀相) 추출 MCP — 사진에서 결정론적 얼굴 피처를 뽑아 구조 JSON으로 돌려준다. MCP-추출, SKILL-지식, AI-해석 합체 패턴으로 MCP는손발(추출) 만 담당한다. 관상 해석·점수·운세는 만들지 않는다(그것은 AI 몫).

원칙

• 외부 API 0. 전부 로컬(MediaPipe FaceLandmarker + 발제선 보정용 selfie_multiclass 세그멘테이션, Apache-2.0). 사진을 어떤 클라우드로도 보내지 않는다.

• 순수 추출. 三停/五官 등 관상 부위명을 키로 쓰지만 의미 부여는 안 한다 — 측정치(비율·각도)만 반환.

• 단일 tool · 단일 호출. 한 번에 완전한 피처를 돌려줘 소형 모델의 다중 tool 호출을 피한다.

Related MCP server: InsightFace-MCP

tool

analyze_face(image, include_overlay=False)

• image: 얼굴 사진. 로컬 파일 경로 / data URI(data:image/jpeg;base64,...) / 순수 base64.

• include_overlay: True면 사용 랜드마크를 찍은 검증용 PNG(base64) 동봉(텍스트 없음 — CJK 폰트 불필요).

반환(JSON)

사람 없음:

{ "is_person": false, "reason": "얼굴이 검출되지 않음(사람 아님 또는 얼굴 미포함)" }

사람 있음:

{
  "is_person": true,
  "features": {
    "samjeong": { "upper": 0.34, "middle": 0.30, "lower": 0.36 },
    "samjeong_meta": { "upper_raw": 0.17, "hairline_estimated": true, "hairline_method": "segment" },
    "ogwan": {
      "eye_length_ratio": 0.18, "interocular_ratio": 0.25,
      "nose_width_ratio": 0.27, "nose_length_ratio": 0.19,
      "mouth_width_ratio": 0.39, "brow_eye_span_ratio": 0.11
    },
    "face_shape_ratio": 1.46,
    "symmetry": 0.94,
    "pose": { "yaw_balance": 0.87, "roll_deg": -9.5 },
    "geometry_px": { "face_width": 79.4, "face_height": 115.6, "face_height_raw": 92.3, "image_w": 512, "image_h": 640 }
  },
  "confidence": "high",
  "notes": []
}

발제선(髮際線) 보정: 랜드마크 메시 최상단(idx 10)은 실제 발제선보다 보통 아래라 상정(上停)이 과소측정된다(전형 정면 검증 7/7). 세그멘테이션으로 정중선의 머리카락↔이마 경계를 잡아 상정·face_height를 재계산한다(높이 정규화 피처도 함께 정상화). samjeong_meta.hairline_method: segment(보정 성공) | fallback(대머리·이마 가림·세그 실패 → 메시-top 회귀, hairline_estimated:false, notes에 안내·상정 축만 저신뢰). upper_raw는 보정 전 값(진위검증·해석층 비교용). face_height_raw는 보정 전 높이.

confidence: "low"면 notes에 사유(측면·흐림·작은 얼굴·기울어짐). v0은 고신뢰 코어만 — 십이궁(十二宮) 좌표매핑·기색(氣色)·귀(耳)는 제외(후속).

실행

~/.local/bin/python3.11 -m venv venv
./venv/bin/python -m pip install -r requirements.txt
./venv/bin/python server.py   # stdio MCP

MCP 등록(헤르메스): command=<repo>/venv/bin/python, args=["<repo>/server.py"], env {}.

왜 SKILL을 함께 주는가 (손발 + 지식)

이 레포는 손발(추출 MCP) 과 지식(해석 SKILL) 을 한 벌로 버전 관리한다. 클론 한 번에 둘 다 따라온다.

MCP만 쓰면 모델이 측정 수치를 즉흥 해석한다 — 재현성도 전거도 없고, 도구가 실패하면 사진을 눈으로 보고 지어내는(환각) 모드로 샌다. 그래서 해석을 skill/의 정적 SKILL로 고정한다:

• ① 전거 인용 — 모든 해석을 측정 키·값에 묶는다(못 묶으면 말하지 않음).

• ② 추측 차단 — 도구 실패·결과 잘림이면 해석 0줄, 재촬영 안내(비전 추측 금지).

• ③ 재현성 — 같은 사진 → 같은 측정 → 같은 해석 틀.

2변형 — 용도에 맞게 하나를 깐다

안티-환각 규율(전거 인용·추측 차단·미측정 부위 언급 금지·면책)은 두 변형 공통, 차이는 표현층뿐. 어느 환경에 무엇을 깔지는 배포 선택이다.

설치 (회사·홈 동일 — 기기 비의존)

1. 레포 클론 + venv + requirements (위 실행).

2. MCP 등록 (위 — command=venv/python, args=[server.py]).

3. 용도에 맞는 변형을 헤르메스 스킬 디렉터리에 SKILL.md로 복사:

   mkdir -p <skills>/gwansang
   cp skill/SKILL.casual.md  <skills>/gwansang/SKILL.md   # 게스트용
   # 또는
   cp skill/SKILL.expert.md  <skills>/gwansang/SKILL.md   # 전문가용

   (<skills>는 해당 프로필의 스킬 디렉터리.)

4. 게이트웨이 재시작으로 스킬 로드.

프라이버시·면책

사진은 메모리에서 MediaPipe로만 처리하고 디스크/네트워크로 내보내지 않는다. 저장·전송 없음. 관상은 얼굴 비율 측정에 기반한 참고용 풀이이며 운명론이 아니다(과학적 사실 아님).

About / 제작

Hermes Agent용 MCP — molpass의 바이브 코딩(vibe coding) 프로젝트.

• 아이디어·방향: molpass (이정훈) · https://zeolinex.com

• 기획: Claude (Chat)

• 개발: Claude Code

같은 모음:

• mcp-saju · mcp-qr · mcp-biorhythm · mcp-astrology · mcp-ziwei · mcp-numerology · mcp-liuren · mcp-qimen · mcp-taiyi · mcp-weather · mcp-newsfeed · mcp-bible

• mcp-gwansang (이 repo)

License

MIT (코드) — molpass. 모델·데이터 출처:

• MediaPipe FaceLandmarker · Selfie Multiclass Segmentation (Google) — Apache-2.0. 모델은 로컬 동봉, 오프라인 추론.