# japan-search-mcp

ジャパンサーチの公式APIを参照する読み取り専用のMCPサーバーです。Python 3.12以上とuv（0.13.4で検証）を使います。上流APIのキー設定は不要です。

## MCPクライアント設定

GitHubリポジトリへのアクセス権がある環境でクローンします。

```sh
git clone https://github.com/koizumikento/japan-search-mcp.git
cd japan-search-mcp
uv sync --locked
```

クライアントの設定に、クローン先の絶対パスを指定します。

```json
{
  "mcpServers": {
    "japan-search-mcp": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/japan-search-mcp", "run", "--locked", "japan-search-mcp"]
    }
  }
}
```

## ツール

| ツール | 用途 |
| --- | --- |
| `search_items` | キーワードで作品・資料を横断検索 |
| `get_item` | アイテムIDでメタデータを取得 |

連携機関がAPI提供を許可した作品・資料メタデータが対象です。画像等の利用条件はアイテムの提供元で確認してください。

## CLI

```sh
uv run japan-search-mcp search-items --query "印象派" --limit 1
uv run japan-search-mcp get-item --item-id bibnl-20706834
```

結果は標準出力にUTF-8のJSONで出力します。コマンドの引数は `uv run japan-search-mcp search-items --help` で確認できます。

## Pythonライブラリ

パッケージをインストールしたPython環境で、下記の非同期関数を直接呼び出せます。

```python
import asyncio

from japan_search_mcp import search_items

result = asyncio.run(search_items(query="印象派", limit=1))
print(result)
```

公開関数 `search_items`、`get_item` を利用できます。イベントループがある環境では、関数を直接 `await` します。

## 出典と利用条件

コードはMIT Licenseです。取得するデータの権利と利用条件は、API提供元と各データ提供機関の定めに従います。[公式API仕様](https://jpsearch.go.jp/static/developer/webapi/ch2_inquiry_api.html) · [利用案内](https://jpsearch.go.jp/static/developer/webapi/ch1_intro.html)

## 開発

```sh
uv sync --locked
uv run ruff check .
uv run ty check
uv run pytest
uv build
```