Exact Match Site ID MCP 커넥터

이 서비스는 Exact Match Site ID 데이터를 ChatGPT, Claude, Cursor 및 MCP 서버를 호출할 수 있는 기타 도구와 같은 MCP 호환 AI 클라이언트에 노출합니다.

스택

• TypeScript

• HTTP 라우팅을 위한 Hono

• MCP 프로토콜 처리를 위한 공식 MCP SDK

• 입력 유효성 검사를 위한 Zod

• 데이터 소스로서의 Laravel data

로컬 설정

1. .env.example을 .env로 복사합니다.

2. LARAVEL_API_BASE_URL을 Laravel API 기본 URL로 설정합니다.

3. LARAVEL_MCP_PROXY_TOKEN을 Laravel의 services.mcp_proxy.internal_token에 설정된 값과 동일하게 설정합니다.

4. OAUTH_TOKEN_SECRET을 최소 32자의 무작위 문자로 설정합니다.

5. npm install로 의존성을 설치합니다.

6. npm run dev로 로컬 개발을 시작합니다.

기본 로컬 서비스 URL은 http://localhost:8787입니다.

유용한 URL

• 상태 확인: GET /health

• MCP 엔드포인트: POST /mcp

• OAuth 인증 메타데이터: GET /.well-known/oauth-authorization-server

• MCP 메타데이터: GET /.well-known/mcp-server

• 위젯: GET /widgets/site-id

개발용 인증

MCP_DEV_AUTH_ENABLED=true일 때, 다음을 호출하여 로컬 인증 코드를 생성할 수 있습니다:

GET /oauth/dev/start?clerk_user_id=user_xxx

운영 환경에서는 이 개발용 핸드오프를 실제 Exact Match/Clerk 로그인 콜백으로 대체해야 합니다.

로컬 OAuth 테스트 흐름

서버를 ChatGPT 앱에 연결하기 전에 이 흐름을 사용하여 로컬에서 OAuth를 테스트하십시오.

1. .env에 로컬 리디렉션 허용 목록이 포함되어 있는지 확인하십시오:

OAUTH_ALLOWED_REDIRECT_URIS=http://localhost:8787/oauth/dev/callback
MCP_DEV_AUTH_ENABLED=true

2. MCP 서버를 시작합니다:

npm run dev

3. 실제 Clerk 사용자 ID로 개발용 인증 URL을 엽니다:

http://localhost:8787/oauth/dev/start?clerk_user_id=user_xxx

브라우저가 다음으로 리디렉션됩니다:

http://localhost:8787/oauth/dev/callback?code=...&state=...

4. 콜백 응답에서 code 값을 복사합니다.

5. 코드를 MCP 액세스 토큰으로 교환합니다:

$code = "paste-code-here"

Invoke-RestMethod `
  -Method Post `
  -Uri "http://localhost:8787/oauth/token" `
  -ContentType "application/x-www-form-urlencoded" `
  -Body @{
    grant_type = "authorization_code"
    client_id = "local-dev"
    redirect_uri = "http://localhost:8787/oauth/dev/callback"
    code = $code
  }

성공적인 응답:

{
  "access_token": "...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "...",
  "scope": "site_id:read"
}

access_token을 다음과 같이 사용하십시오:

Authorization: Bearer <access_token>

이 토큰은 AI 앱 요청을 MCP 서버로 인증합니다. MCP 서버는 여전히 LARAVEL_MCP_PROXY_TOKEN을 사용하여 Laravel에 별도로 인증합니다.