Grips Intelligence MCP 서버 (v2)

Grips Intelligence 이커머스 데이터 API를 Claude Desktop, Cowork, Claude Code 등 모든 MCP 클라이언트에 노출하는 Model Context Protocol (MCP) 서버입니다.

v2는 v1을 완전히 재구축한 버전으로, 초기부터 방어적인 데이터 처리가 적용되었습니다. v1.x에서 런타임 패치가 필요했던 ".map is not a function" 유형의 버그를 수정했습니다. 이제 데이터가 부족하거나 알 수 없는 도메인의 경우, 도구 호출이 중단되는 대신 "데이터 없음"이라는 깔끔한 응답을 반환합니다.

포함된 기능

모든 도구는 가독성을 위해 기본적으로 마크다운 출력을 제공합니다. 기계가 읽을 수 있는 출력을 원하면 format: "json"을 전달하세요.

설치

npm install

npm install을 실행하면 prepare 스크립트가 자동으로 dist/를 빌드합니다.

구성

MCP 클라이언트의 서버 구성에 Grips API 키를 설정하세요. Claude Desktop의 경우 ~/Library/Application Support/Claude/claude_desktop_config.json 파일입니다:

{
  "mcpServers": {
    "grips": {
      "command": "node",
      "args": [
        "/ABSOLUTE/PATH/TO/grips-mcp-server-v2/dist/index.js"
      ],
      "env": {
        "GRIPS_API_KEY": "your-api-key-here",
        "GRIPS_DEFAULT_COUNTRY": "US"
      }
    }
  }
}

필수 환경 변수:

• GRIPS_API_KEY — Grips API 토큰 (grips-api-key 헤더로 전송됨).

선택적 환경 변수:

• GRIPS_DEFAULT_COUNTRY — US, GB 또는 DE. 설정되지 않았거나 유효하지 않으면 기본값은 US입니다.

구성을 편집한 후에는 Claude Desktop을 완전히 종료하고(창을 닫는 것뿐만 아니라 Cmd+Q 사용) 다시 여세요.

v1과의 차이점

v1은 특정 API 응답 형태에서 충돌이 발생했습니다. Grips가 데이터가 부족하거나 알 수 없는 도메인을 반환할 때 timeseries 필드가 null, undefined, []가 아닌 {}로 반환되었기 때문입니다. 기존 코드는 (data.timeseries ?? []).map(...)을 사용했는데, 이는 null/undefined만 방어할 뿐 {}는 방어하지 못했습니다. 결과적으로 "data.timeseries ?? []).map is not a function" 오류가 발생했습니다.

v2는 모든 페이로드 필드를 사용하기 전에 toArray<T>()(배열의 경우) 또는 toObject<T>()(기기 엔드포인트와 같은 딕셔너리 형태 응답의 경우)를 거치도록 라우팅합니다. 배열이나 객체가 아닌 값은 안전한 빈 기본값으로 처리되며, 도구는 오류를 발생시키는 대신 "데이터 없음"이라는 깔끔한 응답을 반환합니다.

기타 변경 사항:

• 날짜 정규화: 모든 도구에서 날짜 형식이 일관되게 (YYYY-MM-DD, UTC 기준) 처리되어 비 UTC 시간대에서도 날짜 경계가 어긋나지 않습니다.

• 통화 / 정수 / 백분율 포맷터: 값이 없는 경우 $NaN이나 0.00% 대신 —를 렌더링합니다.

• 오류 메시지: 이제 401 → "API 키 확인", 429 → "속도 제한, 기간 단축" 등 실행 가능한 힌트가 포함됩니다.

• 도메인별 오류 격리: grips_compare_domains에서 8개 도메인 중 하나에 데이터가 부족해도 나머지 7개의 결과가 깨지지 않습니다.

• 문자열 길이 제한: 응답은 약 200KB로 제한되며, 다중 도메인 추출 시 컨텍스트 창이 초과되지 않도록 알림이 표시됩니다.

개발

npm run dev    # watch mode, rebuilds on change
npm run build  # one-shot build to dist/

명령줄에서 테스트

서버가 오류 없이 부팅되는지 테스트합니다 (stdin에서 EOF를 받으면 종료됩니다):

GRIPS_API_KEY=your-key node dist/index.js < /dev/null

stderr에 [grips-mcp] grips-mcp-server v2.0.0 ready (default country: US).가 표시되고 충돌이 없어야 합니다.

대화형 테스트를 위해서는 @modelcontextprotocol/inspector를 사용하세요:

npx @modelcontextprotocol/inspector node dist/index.js

API 참조

Grips는 공개 스키마를 https://gripsintelligence.com/knowledge-base/api에 문서화하고 있습니다. 이 서버가 사용하는 쿼리는 해당 페이지에서 그대로 복사한 것입니다.

현재 지원되는 국가: US, GB, DE. 그 외의 국가는 API에서 오류가 발생합니다.

라이선스

비공개 — 외부 배포 금지.