Haulistic MCP 服务器

独立的验证概念型 MCP 服务器，为一个 Haulistic 组织暴露只读产品资源。组织通过 MCP_ORGANIZATION_SLUG 在启动时选定；客户端无法选择或更改。

此验证概念有意不包含用户认证。任何能访问 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 可流式 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 之后，然后使用外部可访问的端点配置 Claude 自定义连接器，例如：https://mcp-poc.example.com/mcp。对于这个无需认证、无状态的验证概念，不需要 PUBLIC_MCP_URL 环境变量。

验证概念边界

• 无 OAuth 或其他客户端认证

• 每个部署仅一个组织

• 仅产品资源；没有变更工具

• 公开产品 DTO 有意省略了创建者数据、内部备注、草稿和已删除产品、集成配置以及内部笔记

• 本验证概念不打算成为生产就绪的应用；请勿在公共互联网上公开部署，除非有额外的安全层