Onboard GEO Precheck — MCP 서버 (연동 담당자용)

컨셉브리프를 쓰는 그 자리에서, 랜딩 페이지(또는 Figma 프레임)가 생성형 검색·AI Overview에 인용될 준비가 되어 있는지를 바로 점검하는 얇은 MCP 래퍼입니다. 기존 감사 서비스(Onboard GEO Precheck)는 수정하지 않고, 그 위에 MCP tool 계층만 얹습니다.

접속 주소·비밀번호는 연동 담당자 본인 환경의 값을 넣습니다. 이 레포에는 아무 실값도 담기지 않습니다.

---

제공 도구

도구	하는 일
precheck_url(url, brand_keyword?, category_keyword?, question_keyword?)	라이브 웹페이지 GEO 준비도 감사 → 총점·등급·축별 점수·우선순위 개선 액션 반환
precheck_figma(figma_url, brand_keyword?, …, limit_frames?)	Figma 프레임(?node-id= 포함) 감사 — HTML로 나가기 전 컨셉 단계 사전 점검
get_audit(audit_id)	이전 감사의 전체 상세(채점 근거 facts 포함) 조회

각 도구는 브리프에 바로 붙일 수 있는 report_markdown 블록을 함께 돌려줍니다.

출력 축: AI Overview 준비도 · 브랜드 노출 · 포지션 · 콘텐츠 다양성 · 인용 보너스 → 총점(100)·등급(A~D)

---

설치 (1회)

cd onboard-geo-precheck-mcp
python3 -m venv .venv
./.venv/bin/pip install -r requirements.txt

방식 A — stdio (로컬 실행, 권장)

MCP 클라이언트가 서버를 로컬 프로세스로 실행하는 방식입니다. 클라이언트 설정 파일(예: Claude Desktop claude_desktop_config.json, Cursor ~/.cursor/mcp.json)의 mcpServers에 아래를 추가합니다. 경로·주소·비밀번호는 본인 환경 값으로 바꾸세요.

{
  "mcpServers": {
    "onboard-geo-precheck": {
      "command": "/절대경로/onboard-geo-precheck-mcp/.venv/bin/python",
      "args": ["/절대경로/onboard-geo-precheck-mcp/server.py"],
      "env": {
        "GEO_PRECHECK_BASE_URL": "http://<감사서비스-주소>",
        "GEO_PRECHECK_PASSWORD": "<사이트-비밀번호>"
      }
    }
  }
}

Claude Code CLI라면:

claude mcp add onboard-geo-precheck \
  -e GEO_PRECHECK_BASE_URL=http://<감사서비스-주소> \
  -e GEO_PRECHECK_PASSWORD=<사이트-비밀번호> \
  -- /절대경로/onboard-geo-precheck-mcp/.venv/bin/python /절대경로/onboard-geo-precheck-mcp/server.py

등록 후 클라이언트를 재시작하면 도구가 뜹니다.

방식 B — Remote MCP (URL 하나로 접속)

서버를 HTTP transport로 띄우면 /mcp 엔드포인트가 열리고 Bearer 토큰으로 보호됩니다. 사내 LLM이 URL로 붙는 형태입니다.

서버 실행(HTTP 모드):

GEO_MCP_TRANSPORT=http \
GEO_MCP_PORT=8091 \
GEO_MCP_TOKEN=<발급받은-토큰> \
GEO_PRECHECK_BASE_URL=http://<감사서비스-주소> \
GEO_PRECHECK_PASSWORD=<사이트-비밀번호> \
./.venv/bin/python server.py

MCP 클라이언트 등록(원격 URL + 토큰):

{
  "mcpServers": {
    "onboard-geo-precheck": {
      "url": "http://<서버-호스트>:8091/mcp",
      "headers": { "Authorization": "Bearer <발급받은-토큰>" }
    }
  }
}

• 헬스체크: /healthz (인증 불필요)
• 토큰 없는 /mcp 요청은 401
• 공개 배포 시 GEO_MCP_TOKEN은 반드시 설정

---

사용 예 (컨셉브리프 흐름)

"이 랜딩 컨셉이 AI 검색에 인용될 준비가 됐는지 봐줘: https://example.com/product , 브랜드 키워드는 ○○○"

→ precheck_url 호출 → 총점/등급 + 개선 액션이 나오고, 그대로 브리프의 "GEO 진단" 섹션에 붙이면 됩니다.

---

환경변수

변수	기본값	설명
GEO_PRECHECK_BASE_URL	http://127.0.0.1:8076	감사 서비스 인스턴스 주소(본인 환경 값으로)
GEO_PRECHECK_PASSWORD	(없음, 필수)	사이트 접근 비밀번호(쿠키 세션 자동 처리)
GEO_PRECHECK_TIMEOUT	100	upstream 요청 타임아웃(초)
GEO_MCP_TRANSPORT	stdio	http로 두면 원격 URL 모드
GEO_MCP_HOST	127.0.0.1	http 모드 bind 호스트
GEO_MCP_PORT	8091	http 모드 bind 포트
GEO_MCP_TOKEN	(없음)	http 모드 Bearer 토큰 — 공개 배포 시 반드시 설정

참고 / 한계

• URL 감사는 결정적(deterministic)이고 무료입니다. (유료 LLM 재작성은 이 MCP 범위 밖)
• 매우 무겁거나 느린 페이지는 프록시/터널 타임아웃(약 100초)을 넘겨 502가 날 수 있습니다 — 가벼운 페이지로 재시도하세요.
• 접속 주소·비밀번호·토큰은 각자 환경 값이며, 레포·설정 파일에 커밋하지 마세요.