# 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회)

```bash
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`에 아래를 추가합니다. **경로·주소·비밀번호는 본인 환경 값으로 바꾸세요.**

```json
{
  "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라면:

```bash
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 모드):

```bash
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 + 토큰):

```json
{
  "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`가 날 수 있습니다 — 가벼운 페이지로 재시도하세요.
- 접속 주소·비밀번호·토큰은 각자 환경 값이며, 레포·설정 파일에 커밋하지 마세요.