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 문서를 가져와 그 위에 다 가지 도구를 노출합니다:

이는 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

명시적으로 설정해야 합니다. 이 배포는 /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" }
    }
  }
}

구성 파일을 BOM 없이 UTF-8로 작성하세요.

해당 env 블록에는 자격 증명이 필요 없습니다. 서버는 index.js 옆에 있는 .env를 읽습니다. Claude Desktop은 cwd=/와 거의 빈 환경으로 MCP 서버를 실행하므로, config.js는 작업 디렉터리가 아닌 자신의 파일 위치를 기준으로 .env를 해석합니다. env에 넣은 것은 여전히 우선합니다. 실제 환경 변수가 파일보다 우선합니다.

구성을 편집한 후 Claude Desktop을 완전히 종료하세요(macOS에서 Cmd-Q, 창을 닫는 것만으로는 안 됩니다). 그래야 서버 프로세스가 다시 시작됩니다.

참고 사항 및 주의점

• 자격 증명 범위. BackOffice API 계정은 일반적으로 전체 관리자입니다. uStore에서 제한된 운영자 역할을 지원한다면 그 역할을 사용하세요. 이 서버의 읽기 전용 가드는 사고를 방지하는 것이지, 유출된 토큰을 방지하는 것이 아닙니다.

• **USTORE_ALLOW_PATHS**는 정규식 허용 목록입니다. 이를 설정하면 서버가 실제로 필요한 컨트롤러로 좁혀지며, 이는 쓰기 플래그만으로보다 더 강력한 제어입니다.

• 응답 잘림은 기본적으로 60,000자입니다. 목록 엔드포인트가 넘칠 경우 상한을 높이는 대신 페이지 매김 매개변수를 사용하세요. 이 API는 pageNumber(1부터 시작)와 pageSize(기본 50)로 표기합니다.

• 스펙 캐싱은 15분마다 새로고침됩니다. uStore 업그레이드 후에는 refreshSpec: true와 함께 ustore_server_info를 호출하여 변경 사항을 즉시 반영하세요.

• 연결 실패처럼 보이는 인증 실패. 서버는 자격 증명이 없어도 시작되고 도구를 나열합니다. 로그인은 첫 API 호출 때만 발생합니다. 도구가 표시되지만 모든 호출이 오류를 반환하면 ustore_server_info를 실행하고 hasToken을 확인하세요.

• SQL MCP 서버를 대체하는 것이 아니라 보완합니다. REST API는 uStore의 비즈니스 로직을 적용하므로 상태를 변경하는 모든 작업에 올바른 경로입니다. 직접 [PRODUPRODUCE].ustore 쿼리는 보고용 조인과 스키마 분석에 여전히 더 적합합니다.