# stores-dev-mcp

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

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

**参照するドキュメント**:
- [retail-api-docs](https://github.com/heyinc/retail-api-docs) — ネットショップ・レジ向けREST API (v202211)
- [development-partner-docs](https://github.com/heyinc/development-partner-docs) — OAuth / クレデンシャル認証・パートナーアプリ

---

## セットアップ（5分）

### 前提条件
- Node.js 18 以上

### 手順

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

```bash
npx stores-dev-mcp build
```

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

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

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

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

**Claude Code**:

```bash
claude mcp add stores-dev-mcp -- npx stores-dev-mcp
```

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

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

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

```bash
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） |

**戻り値**:
```json
[
  {
    "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 | 任意 | ドキュメントが大きい場合に特定セクション名を指定 |

---

## 開発

```bash
# 依存インストール
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

```bash
# 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