Haulistic MCP Server

단독형 개념 증명 MCP 서버로, 하나의 Haulistic 조직에 대한 읽기 전용 제품 리소스를 노출합니다. 조직은 시작 시 MCP_ORGANIZATION_SLUG로 선택되며, 클라이언트는 이를 선택하거나 변경할 수 없습니다.

이 POC는 의도적으로 사용자 인증이 없습니다. MCP 엔드포인트에 접근할 수 있는 사람은 누구나 구성된 조직의 공개 카탈로그를 읽을 수 있습니다.

요구 사항

• Node.js 20+

• Haulistic 데이터베이스에 대한 PostgreSQL 연결

• 읽기 전용 액세스 권한이 있는 PostgreSQL 로그인

Related MCP server: MCP Product Search Server

설정

cp .env.example .env
npm install
npm run dev

서버는 MCP_ORGANIZATION_SLUG가 누락되었거나, 삭제되었거나, 비활성화되었거나, 존재하지 않는 경우 시작에 실패합니다.

엔드포인트

• POST /mcp — 상태 비저장 MCP Streamable HTTP 엔드포인트

• GET /health — 데이터베이스 및 구성된 조직 준비 상태 확인

• /mcp의 다른 메서드는 405 Method Not Allowed를 반환합니다

MCP 서버는 다음 리소스 템플릿을 노출합니다:

• haulistic://products/catalog/{offset}/{limit}

• haulistic://products/by-name/{productName}

• haulistic://products/by-route/{productRoute}

활성 상태이고, 목록에 있으며, 삭제되지 않은 제품만 반환됩니다. 카탈로그 제한은 1에서 100 사이여야 합니다. 이름 검색은 대소문자를 구분하지 않는 부분 일치이며 최대 20개의 제품을 반환합니다.

MCP 서버는 또한 다음 재사용 가능한 프롬프트를 노출합니다:

• browse-product-catalog — 카탈로그 페이지 탐색 및 요약

• find-products-by-name — 이름과 일치하는 제품 찾기 및 표시

• compare-products — 스토어프론트 경로를 사용하여 두 제품 비교

읽기 전용 데이터베이스 역할

이 서비스에 대해 별도의 데이터베이스 역할을 사용하세요. 정확한 관리 흐름은 배포 플랫폼에 따라 다르지만, 권한은 다음과 동등해야 합니다:

CREATE ROLE mcp_reader LOGIN PASSWORD 'replace-with-a-secret';
GRANT CONNECT ON DATABASE haulistic TO mcp_reader;
GRANT USAGE ON SCHEMA public TO mcp_reader;
GRANT SELECT ON TABLE
  "Organization",
  "Products",
  "ProductRoutes",
  "ProductOption",
  "ProductOptionValue"
TO mcp_reader;
ALTER ROLE mcp_reader SET default_transaction_read_only = on;

애플리케이션은 또한 모든 데이터베이스 연결에 대해 default_transaction_read_only=on을 요청하고 구성 가능한 명령문 시간 제한을 적용합니다. 데이터베이스 권한은 기본 보안 경계로 유지됩니다.

빌드 및 실행

npm run build
npm start

또는 컨테이너를 빌드:

docker build -t haulistic-mcp-server .
docker run --rm -p 8080:8080 --env-file .env haulistic-mcp-server

서비스를 HTTPS 뒤에 배포한 다음, 외부에서 접근 가능한 엔드포인트(예: https://mcp-poc.example.com/mcp)로 Claude 사용자 지정 커넥터를 구성하세요. 이 인증되지 않은 상태 비저장 POC에는 PUBLIC_MCP_URL 환경 변수가 필요하지 않습니다.

POC 경계

• OAuth 또는 기타 클라이언트 인증 없음

• 배포당 하나의 조직

• 제품 리소스만; 변경 도구 없음

• 공개 제품 DTO는 의도적으로 작성자 데이터, 내부 메모, 초안 및 삭제된 제품, 통합 구성, 내부 타임스탬프를 생략합니다