# furunavi-mcp-community

ふるさと納税サイト「ふるなび」を扱う**非公式**のMCPサーバーです。MVPとして、返礼品検索、詳細取得、ブラウザログイン、お気に入り追加を提供します。

> ふるなび運営会社とは無関係です。個人利用を前提とし、サイトの利用規約・robots・アクセス制限を尊重してください。寄附申込みや決済は実装していません。

## MCP tools

| Tool | 用途 | ログイン |
|---|---|---|
| `furunavi_search_products` | キーワード検索 | 不要 |
| `furunavi_get_product` | 返礼品IDによる詳細取得 | 不要 |
| `furunavi_auth_status` | セッション保存状況 | 不要 |
| `furunavi_auth_login` | ブラウザで対話ログイン | 操作が必要 |
| `furunavi_auth_clear` | 保存セッション削除 | 不要 |
| `furunavi_add_favorite` | お気に入り追加（冪等） | 必要 |

## Setup

npm公開版を利用する場合：

```bash
npm install -g furunavi-mcp-community
npx playwright install chromium
```

ソースから開発する場合：

```bash
git clone https://github.com/new-village/furunavi-mcp-community.git
cd furunavi-mcp-community
npm install
npx playwright install chromium
npm run build
```

Claude Desktop / Claude Code等の設定例：

```json
{
  "mcpServers": {
    "furunavi": {
      "command": "npx",
      "args": ["-y", "furunavi-mcp-community"]
    }
  }
}
```

## Login

パスワードをMCPへ渡さず、利用者がふるなびの画面で直接ログインします。

```bash
node dist/index.js auth
node dist/index.js auth --status
node dist/index.js auth --clear
```

保存先は `~/.config/furunavi-mcp-community/storage-state.json`（mode 0600）です。`FURUNAVI_MCP_CONFIG_DIR` で変更できます。

### リモート・コンテナ環境

headedブラウザを表示できる端末でログインしてください。Remote SSHやヘッドレスサーバーではブラウザ画面を操作できないため、同一ユーザーの設定ディレクトリを安全に移送・マウントする必要があります。storage-stateには認証Cookieが含まれるため、Gitへ追加したり共有したりしないでください。

## Development

```bash
npm test
npm run typecheck
npm run build
npm run lint
npm audit --omit=dev
npm pack --dry-run
```

Node.js 20以上を使用します。HTML構造変更により解析処理が壊れる可能性があるため、公開前には実サイトsmoke testを実行してください。