ustore-backoffice-mcp

用于 XMPie uStore BackOffice REST API 的 MCP 服务器，API 地址为 https://produproduce.mysite.com/ustorebackofficerestapi。

状态：可用，已针对线上 API 完成端到端验证。 规范加载成功（15 个标签组下共 52 个路径 / 63 个操作），登录成功，ustore_call_endpoint GET /v1/admin/stores 返回 HTTP 200。只读保护正确拒绝了 DELETE 请求。

设计

服务器不会硬编码端点。首次使用时，它会获取 API 自身的 OpenAPI 3.0 文档，并基于该文档暴露五个工具：

这与 MSSQL MCP 服务器的形态相同（list_databases → list_tables → describe_table → query），无论 API 暴露多少端点，工具数量都保持精简。它还能经受 uStore 升级——新端点会在下次规范刷新时自动出现。

写入操作默认禁用。在服务器进程上设置 USTORE_ALLOW_WRITES=true 之前，非 GET 方法都会被拒绝。

Related MCP server: mcp-db-server

设置

必须运行在能够通过内部网络访问 produproduce 的主机上。

cd /opt/mcp/ustore-backoffice-mcp
npm install
cp .env.example .env
$EDITOR .env          # credentials — the base URL and spec URL are preset
npm run probe         # optional: re-confirm the spec URL and auth handshake

认证握手已针对线上 API 验证通过，并且已是默认配置：

POST {base}/v1/admin/auth/login   {"email": "...", "password": "..."}
  -> 200 {"Token": "..."}

Authorization: uStoreBackoffice <token>     # on every subsequent request

注意登录请求体使用 email 而非 username，令牌字段为大写 Token。认证方案字面就是 uStoreBackoffice——API 会以 {"Errors":[{"Message":"Invalid security token."}]} 拒绝任何其他前缀。

规范 URL 同样已确认并预设：

USTORE_SPEC_URL=https://produproduce.mysite.com/ustorebackofficerestapi/ustore-oas3

必须显式设置——此部署在 /ustore-oas3 提供 OAS3，否则 loadSpec() 会探测的路径全部返回 404。

然后：

npm run http          # or: npm run stdio

验证：

$ curl -s localhost:8931/healthz
{"ok":true,"target":"https://produproduce.mysite.com/ustorebackofficerestapi"}

/healthz 只能证明进程在运行。要确认 API 链路正常，请从客户端调用 ustore_server_info——它会报告解析后的认证方案和操作数量，如果登录失败会明确报错。

部署

pm2

pm2 start index.js --name ustore-mcp --node-args="--enable-source-maps"
pm2 save

systemd

[Unit]
Description=uStore BackOffice MCP server
After=network-online.target

[Service]
Type=simple
User=tc
WorkingDirectory=/opt/mcp/ustore-backoffice-mcp
EnvironmentFile=/opt/mcp/ustore-backoffice-mcp/.env
ExecStart=/usr/bin/node index.js
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

将 .env 的权限保持为 chmod 600——其中保存着 uStore BackOffice 凭据，属于管理员级凭据。

HAProxy

SSE 需要关闭缓冲并设置较长的服务器超时时间，否则会话会被切断：

backend be_mcp_ustore
    mode http
    option http-server-close
    timeout server 3600s
    timeout tunnel 3600s
    http-request set-header X-Accel-Buffering no
    server ustore1 127.0.0.1:8931 check

两种传输方式都已提供：POST /mcp（Streamable HTTP，当前规范）和 GET /sse + POST /messages（旧版 SSE，与现有技术栈一致）。如果希望服务器自身校验共享密钥，而不是仅依赖 HAProxy ACL，请设置 MCP_BEARER_TOKEN。

客户端配置

本地 stdio（同一台机器上的 Claude Desktop）：

{
  "mcpServers": {
    "ustore-backoffice": {
      "command": "node",
      "args": ["/opt/mcp/ustore-backoffice-mcp/index.js"],
      "env": { "MCP_TRANSPORT": "stdio" }
    }
  }
}

将配置文件保存为 UTF-8 编码，不要带 BOM。

该 env 块中不需要任何凭据：服务器会读取与 index.js 同目录的 .env 文件。Claude Desktop 以 cwd=/ 和近乎空的环境启动 MCP 服务器，因此 config.js 会基于自身文件位置而非工作目录来解析 .env。你放在 env 中的任何内容仍然优先——真实环境变量优先于文件。

编辑配置后，完全退出 Claude Desktop（macOS 上按 Cmd-Q，而不是仅关闭窗口），以便服务器进程重新启动。

注意事项与陷阱

• 凭据范围。 BackOffice API 账户通常是完全管理员权限。如果 uStore 支持受限的操作员角色，请使用该角色——本服务器的只读保护针对的是意外操作，而非令牌泄露。

• USTORE_ALLOW_PATHS 是一个正则表达式白名单。设置它可以限制服务器只暴露你实际需要的控制器，这比单独的写入标志是更强大的控制手段。

• 响应截断 默认上限为 60k 字符。如果列表端点超出限制，请使用其分页参数而不是提高上限——此 API 的分页参数为 pageNumber（从 1 开始）和 pageSize（默认 50）。

• 规范缓存 每 15 分钟刷新一次。uStore 升级后，调用 ustore_server_info 并传入 refreshSpec: true 可立即获取变更。

• 看似连接失败实则认证失败。 即使缺少凭据，服务器也会启动并列出工具——登录只会在首次 API 调用时发生。如果工具已出现但每次调用都报错，请运行 ustore_server_info 并检查 hasToken。

• 这是对 SQL MCP 服务器的补充，而非替代。 REST API 强制执行 uStore 的业务逻辑，因此它是任何状态变更操作的正确路径。直接查询 [PRODUPRODUCE].ustore 仍然更适合报表联表和架构考古。