stores-dev-mcp

⚠️ Unofficial. Not affiliated with STORES, Inc. (st.inc)

STORES のAPIドキュメントをAIクライアント（Claude Desktop / Claude Code等）に提供するMCPサーバーです。 Shopify公式の dev-mcp と同等のドキュメント参照体験を、STORESの公開ドキュメントで実現します。

参照するドキュメント:

• retail-api-docs — ネットショップ・レジ向けREST API (v202211)
• development-partner-docs — OAuth / クレデンシャル認証・パートナーアプリ

---

セットアップ（5分）

前提条件

• Node.js 18 以上

手順

1. インデックスを構築する

npx stores-dev-mcp build

GitHubからドキュメントを取得して ~/.stores-dev-mcp/index.json を生成します（インターネット接続が必要）。

2. MCPクライアントに登録する

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "stores-dev-mcp": {
      "command": "npx",
      "args": ["stores-dev-mcp"]
    }
  }
}

Claude Code:

claude mcp add stores-dev-mcp -- npx stores-dev-mcp

または .claude/settings.json に直接記述:

{
  "mcpServers": {
    "stores-dev-mcp": {
      "command": "npx",
      "args": ["stores-dev-mcp"]
    }
  }
}

3. ドキュメントを更新する

npx stores-dev-mcp build

同じコマンドを再実行するだけで最新のドキュメントを取り込みます。

---

使い方

AIクライアントで以下のように依頼してください：

STORESのAPIでオーダーを期間指定で取得する方法を教えて

内部では次のフローで応答します：

1. learn_stores_api — 全体像とドキュメントパス一覧を取得
2. search_docs("オーダー 期間指定") — 関連チャンクを検索
3. fetch_full_doc("retail/get-retail-202211-orders") — エンドポイント全文を取得
4. 実際のパラメータ名・型・フォーマットに基づいてコードを生成

---

ツール仕様

learn_stores_api

STORES API の全体像・認証方式・ドキュメントパス一覧を返します。会話の冒頭に呼ばせることでハルシネーションを防ぎます。

パラメータ	型	必須	説明
topic	"retail" | "partner"	任意	省略時は両方

search_docs

BM25でドキュメントを全文検索します。日英どちらのキーワードでも検索できます。

パラメータ	型	必須	説明
query	string	✓	自然文またはキーワード
limit	integer (1–20)	任意	返す件数（デフォルト: 5）

戻り値:

[
  {
    "path": "retail/get-retail-202211-orders",
    "heading": "GET /retail/202211/orders - オーダー一覧",
    "excerpt": "オーダーの一覧をオーダーされた日時の降順で...",
    "score": 26.63
  }
]

fetch_full_doc

search_docs が返した path のドキュメント全文を返します。パラメータの型・必須/任意・詳細説明を含みます。

パラメータ	型	必須	説明
path	string	✓	search_docs が返した path 値
section	string	任意	ドキュメントが大きい場合に特定セクション名を指定

---

開発

# 依存インストール
npm install

# TypeScriptビルド
npm run build

# テスト
npm run test

# ドキュメント取り込み（インデックス構築）
npm run build:docs

# MCP Inspector で動作確認
npm run inspector

アーキテクチャ

src/
├── index.ts          # エントリーポイント
├── server.ts         # MCPサーバー（stdio）
├── ingest.ts         # ドキュメント取り込み・インデックス構築
├── tools/
│   ├── learn.ts      # learn_stores_api
│   ├── search.ts     # search_docs
│   └── fetch.ts      # fetch_full_doc
└── search/
    ├── bm25.ts       # BM25スコアリング（ゼロ依存）
    ├── tokenizer.ts  # CJK bigram + ASCII単語のハイブリッドトークナイザ
    └── synonyms.ts   # 日英シノニム正規化

~/.stores-dev-mcp/
└── index.json        # 生成インデックス（npmに含まれない）

検索アルゴリズム:

• BM25 (k1=1.5, b=0.75)
• 日本語: bigramトークン化
• 英語: 単語単位トークン化
• 見出しトークンに2倍の重み
• 日英シノニム正規化（オーダー / 注文 / order を同一視等）

---

FAQ

Q: インデックスはどこに保存されますか？
A: ~/.stores-dev-mcp/index.json に保存されます。npmパッケージには含まれません。

Q: ドキュメントが更新されたら？
A: npx stores-dev-mcp build を再実行してください。

Q: オフラインで使えますか？
A: インデックス構築（npx stores-dev-mcp build）はインターネット接続が必要です。構築後のMCPサーバーはオフラインで動作します。

Q: STORESの公式ツールですか？
A: いいえ。これは非公式ツールです。STORES, Inc. (st.inc) とは一切関係ありません。

---

ライセンス

MIT

---

stores-dev-mcp (English)

⚠️ Unofficial. Not affiliated with STORES, Inc. (st.inc)

An MCP server that provides STORES API documentation to AI clients (Claude Desktop / Claude Code, etc.).

Quick Start

# Build the documentation index
npx stores-dev-mcp build

# Add to Claude Desktop config
# ~/Library/Application Support/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "stores-dev-mcp": {
      "command": "npx",
      "args": ["stores-dev-mcp"]
    }
  }
}

Tools

Tool	Description
learn_stores_api	Returns an overview of the STORES API — auth methods, endpoints, and available doc paths
search_docs	BM25 full-text search over API documentation (supports Japanese and English)
fetch_full_doc	Returns the full content of a document given a path from search_docs

License

MIT