ustore-backoffice-mcp

https://produproduce.mysite.com/ustorebackofficerestapi にある XMPie uStore BackOffice REST API 用の MCP サーバー。

ステータス: 動作確認済み、実 API に対してエンドツーエンドで検証済み。 スペックの読み込み（15 のタググループにわたる 52 パス / 63 オペレーション）、ログイン、ustore_call_endpoint GET /v1/admin/stores の HTTP 200 応答を確認済み。読み取り専用ガードは DELETE を正しく拒否します。

設計

このサーバーはエンドポイントをハードコードしません。初回使用時に API 自身の OpenAPI 3.0 ドキュメントを取得し、その上に 5 つのツールを公開します:

これは 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

ログインボディは username ではなく email を使用し、トークンフィールドは大文字の Token であることに注意してください。スキームは文字通り uStoreBackoffice です — API は他のプレフィックスを {"Errors":[{"Message":"Invalid security token."}]} で拒否します。

スペック URL も同様に確認済みで、プリセットされています:

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

これは明示的に設定する必要があります — このデプロイメントは OAS3 を /ustore-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" }
    }
  }
}

設定ファイルは BOM なしの UTF-8 で書き込んでください。

その env ブロックには資格情報は不要です: サーバーは index.js の隣にある .env を読み取ります。Claude Desktop は MCP サーバーを cwd=/ とほぼ空の環境で起動するため、config.js は作業ディレクトリではなく自身のファイル位置に対して .env を解決します。env に入れたものは引き続き優先されます — 実際の環境変数はファイルより優先されます。

設定を編集した後は、Claude Desktop を完全に終了してください（macOS ではウィンドウを閉じるだけでなく Cmd-Q）— サーバープロセスが再起動されるように。

注意点と落とし穴

• 資格情報の範囲。 BackOffice API アカウントは通常、完全な管理者権限を持ちます。uStore が制限付きオペレーターロールをサポートしている場合は、それを使用してください — このサーバーの読み取り専用ガードは事故を防ぐものであり、侵害されたトークンを防ぐものではありません。

• USTORE_ALLOW_PATHS は正規表現の許可リストです。これを設定すると、サーバーを実際に必要なコントローラに絞り込めます。これは書き込みフラグ単独よりも強力な制御です。

• レスポンスの切り詰めはデフォルトで 60k 文字です。リストエンドポイントがオーバーフローする場合は、上限を上げるのではなくページングパラメータを使用してください — この API では pageNumber（1 始まり）と pageSize（デフォルト 50）と表記されます。

• スペックのキャッシュは 15 分ごとに更新されます。uStore のアップグレード後は、refreshSpec: true を指定して ustore_server_info を呼び出し、変更をすぐに反映してください。

• 接続障害のように見える認証障害。 サーバーは資格情報がなくても起動し、ツールを一覧表示します — ログインは最初の API 呼び出しでのみ発生します。ツールが表示されるのにすべての呼び出しがエラーになる場合は、ustore_server_info を実行して hasToken を確認してください。

• これは SQL MCP サーバーを補完するものであり、置き換えるものではありません。 REST API は uStore のビジネスロジックを強制するため、状態を変更するものには正しい経路です。直接の [PRODUPRODUCE].ustore クエリは、レポート用の結合やスキーマの調査には引き続き適しています。