catalog-mcp

모든 JSON 카탈로그를 AI 에이전트용 쿼리 도구로 변환하는 MCP 서버입니다.

카탈로그 URL이나 파일(재고 피드, 제품 목록, feedmerge가 게시하는 catalog.json)을 지정하면, 모든 MCP 클라이언트(Claude Desktop, Claude Code, 프로토콜을 지원하는 모든 것)가 레코드에 대해 구조화된 필터링, 그룹화, 순위 지정, 스키마 탐색을 수행할 수 있습니다.

Node 18+. 두 개의 런타임 의존성: MCP SDK와 zod.

Why

에이전트는 큰 JSON 파일을 다루지 못하고 도구를 잘 활용합니다. 에이전트에게 2MB 카탈로그를 주면 레코드를 자르거나, 대충 읽거나, 환각을 일으키지만, 필터 문법이 있는 catalog_query를 주면 "이 두 기능을 갖춘 3만 달러 미만의 가장 저렴한 레코드"를 매번 정확하게 답하며, 조건에 맞는 레코드만 읽습니다.

이 저장소는 제가 프로덕션에서 운영하는 MCP 서버의 일반화된 버전입니다. 매장 현장의 AI 어시스턴트가 정확히 이 도구들(동일한 필터 의미론, 동일한 null 가격 규칙, 동일한 TTL 캐시)을 사용하여 하루 수백 번 실시간 재고 카탈로그를 조회합니다. 이 파이프라인이 속한 구조는 다음과 같습니다:

vendor feed  ->  feedmerge  ->  catalog.json  ->  catalog-mcp  ->  any agent
             (guarded sync)   (versioned)      (query tools)

저는 이 서버를 제 공개 재고 피드에 대해 실행합니다. 아래 예제는 저장소가 독립적으로 작동할 수 있도록 중립적인 카탈로그를 사용합니다.

Quickstart

git clone https://github.com/stevyf93II/catalog-mcp.git
cd catalog-mcp
npm install
npm test                                          # engine, loader, and stdio end-to-end tests

# serve the example catalog
node src/server.js --file examples/telescopes.json --key sku

Claude Desktop에 연결합니다 (claude_desktop_config.json):

{
  "mcpServers": {
    "my-catalog": {
      "command": "node",
      "args": ["/path/to/catalog-mcp/src/server.js"],
      "env": {
        "CATALOG_URL": "https://example.com/catalog.json",
        "CATALOG_KEY": "sku"
      }
    }
  }
}

그런 다음 에이전트에게 "카탈로그에 어떤 유형이 있고 각각의 최저 가격은 얼마인가요?"와 같은 질문을 하면, 에이전트가 catalog_schema, catalog_count_by, catalog_top을 스스로 조합하여 사용하는 것을 지켜보세요.

Tools

모든 도구는 읽기 전용이며 멱등적이며, MCP 주석에 그렇게 명시되어 있습니다.

The filter grammar

query, count_by, top에서 사용하는 하나의 작은 명세:

{
  "eq":       { "type": "reflector", "goto": true },
  "min":      { "aperture_mm": 150 },
  "max":      { "price": 1000 },
  "has":      { "features": ["Parabolic Mirror", "Cooling Fan"] },
  "contains": { "name": "dobsonian" }
}

• eq — 불리언과 null을 포함한 모든 값에 대한 엄격한 동등성.

• min / max — 숫자 범위. 경계가 있는 필드에 실제 숫자가 없는 레코드는 제외됩니다. 이 규칙은 중요합니다. 프로덕션 카탈로그에서 가격이 없으면 "가격 문의"를 의미하며, "3만 달러 미만의 유닛을 보여줘"라는 요청에 가격을 알 수 없는 유닛이 절대 표시되어서는 안 됩니다.

• has — 배열 멤버십; 나열된 모든 값이 존재해야 합니다.

• contains — 문자열 필드에 대한 대소문자 구분 없는 부분 문자열; 필드 "*"는 레코드의 모든 문자열 필드를 검색합니다.

조건은 AND로 결합됩니다. 알 수 없는 최상위 키는 유효한 키를 명명하는 오류를 발생시킵니다. 조용히 무시되는 필터는 에이전트가 자신 있게 잘못된 답변을 보고하는 방법이기 때문입니다.

정렬은 정렬 필드가 없는 레코드를 양방향 모두 끝으로 밀어냅니다. "가격순 정렬"은 null의 벽이 아니라 가격이 있는 레코드를 먼저 보여줍니다.

Configuration

CATALOG_RECORDS_PATH가 설정되지 않은 경우, 로더는 문서 루트가 배열이면 그것을 사용하고, 정확히 하나의 최상위 객체 배열이 있으면 그것을 사용합니다 ({ "meta": ..., "items": [...] }는 그냥 작동합니다). 문서가 모호하면 거부하고 후보 키를 명명합니다.

새로고침에 실패하면 서버는 오류를 반환하는 대신 마지막으로 유효한 데이터를 제공합니다. 작업 중인 에이전트는 예외보다 5분 전 레코드가 더 낫기 때문입니다. 그리고 catalog_stats는 캐시 기간을 보고하여 데이터의 오래됨이 숨겨지지 않도록 합니다.

Non-goals

• 데이터베이스가 아닙니다. 카탈로그는 읽기 전용이며 메모리에 상주합니다. 데이터가 JSON 파일에 편안하게 들어가지 않는다면 실제 저장소가 필요합니다.

• 쓰기 작업이 없습니다. 여기서는 카탈로그를 변경하지 않습니다. 이는 동기화 파이프라인의 작업입니다 (feedmerge 참조).

• 쿼리 언어가 없습니다. 다섯 개의 필터 키로 에이전트가 실제로 묻는 내용을 처리합니다. 더 복잡한 것은 코드에 속하며 도구 스키마에 속하지 않습니다.

License

MIT