Store Sales Data Server

このプロジェクトは、CSV で管理している店舗売上データを MCP サーバー経由で取得・保存できるようにしたサンプルです。現在の実装では、店舗一覧とメニュー一覧の取得、取得可能日付の一覧化、期間指定の明細取得、1 日分の売上保存を提供しています。

必要な環境

• Node.js 20 以降
• npm, npx が使えること
• MCP クライアント 例: Claude Desktop, MCP Inspector

セットアップ

リポジトリをクローンして依存関係をインストールします。

git clone https://github.com/eXpresser-UXM/20260617-dx-dojo-mcp-server-sample.git
cd 20260617-dx-dojo-mcp-server-sample
npm install

MCP サーバーが正しく起動するか確認するには、インスペクタを使います。

npm run inspect

起動するとブラウザが開くので、左側ペインの Connect を押して接続します。接続できると、右側ペインでサーバー名の「売上管理システム」が表示されます。上部の Tools から List Tools を開くと、登録済みツールの一覧が確認できます。

MCP クライアント設定例

Claude Desktop などの MCP クライアントから使う場合は、次のように設定します。/path/to/this/project はこのプロジェクトのルートに置き換えてください。

{
  "mcpServers": {
    "dx-dojo-sample-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "tsx",
        "/path/to/this/project/mcp/main-stdio.ts"
      ]
    }
  }
}

クライアントを再起動したあと、たとえば次のような指示で動作確認できます。

2025年12月の全店舗の売上を確認してください。

全体像

• エントリポイントは mcp/main-stdio.ts
• サーバーの組み立ては mcp/mcp-server.ts
• 個別の機能は mcp/tools 配下
• データ本体は storage 配下の JSON と CSV

登録されているツール

mcp/tools/get-stores.ts

店舗名の一覧を storage/_stores.json から取得します。売上データの保存や参照の前に、対象店舗を確認するときに使います。

mcp/tools/get-items.ts

メニュー一覧を storage/_menus.json から取得します。メニュー名と単価を確認したいときに使います。

mcp/tools/list-available-date.ts

storage 配下の CSV を走査して、店舗ごとに取得可能な日付をまとめて返します。ファイル名は YYYYMMDD_店舗名.csv の形式を前提にしています。

mcp/tools/get-sales-rowdata.ts

指定した店舗名と期間の売上明細を返します。存在しない日付の CSV は無視し、ある日だけをまとめて返します。返却される明細はメニュー名、単価、数量、金額です。

mcp/tools/save-daily-sales.ts

1 日分の売上明細を CSV として保存します。店舗名の妥当性を確認し、メニュー一覧に存在する商品だけを受け付けます。保存時の金額は単価と数量から再計算されます。

データ配置

• storage/_stores.json: 店舗名一覧
• storage/_menus.json: メニュー一覧
• storage/csv: 日別売上 CSV

使い方の流れ

1. 店舗名とメニュー名を取得する
2. 取得可能日付を確認する
3. 期間を指定して売上明細を取得する
4. 必要に応じて 1 日分の売上を保存する

この流れに沿うと、AI クライアントからでも手作業でも扱いやすくなります。