Haulistic MCP Server

単独で動作する概念実証のMCPサーバーで、1つのHaulistic組織の読み取り専用の製品リソースを公開します。組織は起動時にMCP_ORGANIZATION_SLUGで選択され、クライアントが選択または変更することはできません。

このPOCは意図的にユーザー認証を実装していません。MCPエンドポイントに到達できる人は誰でも、設定された組織の公開カタログを読み取ることができます。

要件

• Node.js 20+

• PostgreSQL を使用した Haulistic データベースへの接続

• 読み取り専用アクセス権を持つ PostgreSQL ログイン

Related MCP server: zee5-catalog-mcp

セットアップ

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 — ストアフロントルートを使用して2つの製品を比較する

読み取り専用データベースロール

このサービスには別のデータベースロールを使用してください。正確な管理フローはデプロイメントプラットフォームに依存しますが、権限は次のと同等である必要があります：

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の背後にデプロイし、外部から到達可能なエンドポイントを使用してClaudeカスタムコネクタを構成します。例：https://mcp-poc.example.com/mcp。この認証なしのステートレスなPOCには、PUBLIC_MCP_URL環境変数は必要ありません。

POCの制約

• OAuthやその他のクライアント認証なし

• デプロイメントごとに1つの組織

• 製品リソースのみ。変更ツールはなし

• 公開製品DTOは、作成者データ、内部メモ、下書きおよび削除された製品、統合設定、および