# kaken-mcp-server

科学研究費助成事業データベース（**KAKEN**）の公式 OpenSearch API を Claude から利用するためのローカル MCP サーバ。`claude_desktop_config.json` の `env` 経由で `KAKEN_APPID` を渡せるため、Win/Mac の Claude Desktop で確実に動作する。

提供ツール：

| ツール名 | 用途 |
|---------|------|
| `kaken_search_projects` | 研究課題を多条件で検索（kw/qa/qb/qg/qh/qm/qc/qd/qe/qf/s1/s2/o1/od） |
| `kaken_search_researchers` | 研究者を検索（kw/qg/qm/qh/qq/qs/qe/qd） |
| `kaken_get_project` | 課題番号から1件の詳細取得 |
| `kaken_get_researcher_grants` | 研究者番号から関与全課題を取得（業績把握用） |

## 0. インストール方法（3通り）

すべての方法で、先に [CiNii API 利用登録](https://support.nii.ac.jp/ja/cinii/api/developer) でアプリケーションID（appid）を取得しておくこと。

### A. Claude Desktop 拡張機能（.mcpb バンドル）— 推奨

[Releases](../../releases) から `kaken-mcp-server-x.y.z.mcpb` をダウンロードし、ダブルクリック（または Claude Desktop の 設定 → 拡張機能 にドラッグ&ドロップ）。インストールダイアログで appid を入力するだけで使える。Node.js のインストールも不要（Claude Desktop 内蔵ランタイムで動作）。

`.mcpb` を自分でビルドする場合：

```bash
npm install
npm run build                 # tsc → dist/
node scripts/build-mcpb.mjs   # kaken-mcp-server-x.y.z.mcpb を生成
```

> Note: `npx @anthropic-ai/mcpb pack` は使わない。新しい mcpb CLI が生成する zip
> （ディレクトリエントリ無し・小構成）だと Claude Desktop のインストーラが
> "reply was never sent" で無応答になる。`scripts/build-mcpb.mjs` はインストール
> 実績のある形式（dist + production node_modules 同梱、dir エントリ +
> unix ファイル種別ビット付き zip）で生成する。
> なお `npm run bundle`（esbuild 単一ファイル `server/index.cjs`）は
> Claude Code プラグイン用で、.mcpb には使わない。

### B. Claude Code プラグイン（マーケットプレイス経由）

```
/plugin marketplace add masa-med-ai/kaken-mcp-server
/plugin install kaken-search@kaken-marketplace
```

appid は環境変数で渡す（シェルの rc ファイル等に設定）：

```bash
export KAKEN_APPID="YOUR_APPID_HERE"
```

### C. 手動セットアップ（claude_desktop_config.json）

以下の手順1〜3を参照。

## 1. 手動セットアップ

### 1-1. appid を取得

[CiNii API 利用登録](https://support.nii.ac.jp/ja/cinii/api/developer) でアプリケーションID（appid）を取得する。

### 1-2. このリポジトリを準備

```bash
git clone <this-repo>  # または手動配置
cd kaken-mcp-server
npm install
npm run build
```

`dist/index.js` が生成される。

### 1-3. claude_desktop_config.json に登録

設定ファイルの場所：

- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

以下を追記する（既存の `mcpServers` がある場合はその中にマージ）：

```json
{
  "mcpServers": {
    "kaken": {
      "command": "node",
      "args": ["/絶対パス/kaken-mcp-server/dist/index.js"],
      "env": {
        "KAKEN_APPID": "YOUR_APPID_HERE"
      }
    }
  }
}
```

**Windows の例**（パス区切りに注意。バックスラッシュは `\\` でエスケープ）：

```json
{
  "mcpServers": {
    "kaken": {
      "command": "node",
      "args": ["C:\\Users\\<name>\\kaken-mcp-server\\dist\\index.js"],
      "env": {
        "KAKEN_APPID": "YOUR_APPID_HERE"
      }
    }
  }
}
```

設定後、Claude Desktop を再起動するとツールが利用可能になる。

## 2. 動作確認

Claude に以下のように依頼すれば、自動的にツールが呼ばれる：

- 「KAKEN で AI 内視鏡の先行研究を調べて」
- 「研究者番号 80802743 の科研費業績を取得して」
- 「19K20626 の研究課題の詳細を見せて」
- 「昭和大学の消化器内科学分野の課題を年度別に集計して」

## 3. ツール仕様

### `kaken_search_projects`

| 引数 | 型 | 説明 |
|------|----|------|
| `kw` | string | フリーワード検索（全フィールド対象） |
| `qa` | string | 研究課題名で検索 |
| `qb` | string | 研究課題番号（例: `19K20626`） |
| `qg` | string | 研究者の姓名 |
| `qh` | string | 研究者の所属機関 |
| `qm` | string | 研究者番号（8桁） |
| `qc` | string | 研究種目（例: `若手研究`） |
| `qd` | string | 審査区分/研究分野 |
| `qe` | string | 研究機関 |
| `qf` | string | キーワード |
| `s1` | string | 助成開始年度 From |
| `s2` | string | 助成終了年度 To |
| `o1` | `1`-`4` | 助成期間の検索条件（1=開始年度〈既定〉, 2=終了年度, 3=期間の一部, 4=全部） |
| `od` | `1`-`5` | ソート（1=適合度, 2=開始年新しい順〈既定〉, 3=古い順, 4=配分額多い順, 5=少ない順） |
| `rw` | integer | 1ページの件数（20/50/100/200/500、既定100。中間値は近い許容値に切り上げ） |
| `start` | integer | 開始位置（既定1） |
| `lang` | `ja` / `en` | 言語（既定 `ja`） |
| `format` | `ai` / `table` / `json` | 出力形式（既定 `ai`） |

### `kaken_search_researchers`

`kw`, `qg`, `qm`, `qh`（現在の所属機関）, `qq`（部局）, `qs`（職名）, `qe`, `qd`, `rw`, `start`, `lang`, `format` を受け取る。

研究者検索API（nrid.nii.ac.jp）は XML 非対応のため、内部では `format=json` で取得して
パースしている（研究課題検索は従来どおり XML）。取得可能な検索結果は最大1000件。

### `kaken_get_project`

- `awardNumber` (必須): KAKEN研究課題番号
- `format`: `ai` / `json`

### `kaken_get_researcher_grants`

- `researcherNumber` (必須): 研究者番号
- `rw`: 件数（既定200。一人の研究者の全課題を取得するため大きめ）
- `format`: `ai` / `table` / `json`

## 4. 出力形式

`ai`（既定）は AI に読ませやすい圧縮 Markdown：

```
## 1. [19K20626] IIIFとTEIを用いたオンライン翻刻支援システムの開発
- 研究代表者: 中村 覚（80802743）/ 東京大学 史料編纂所 / 助教
- 研究種目: 若手研究
- 研究期間: 2019-04-01 〜 2023-03-31
- 状態: 完了
- 配分額: 直接 ¥3,500,000 / 間接 ¥1,050,000 / 合計 ¥4,550,000
- キーワード: IIIF, TEI, 人文情報学
- URL: https://kaken.nii.ac.jp/grant/KAKENHI-PROJECT-19K20626/
```

`table` は Markdown のテーブル、`json` は構造化データ。

## 5. 開発

```bash
npm run dev      # tsx で直接実行（ホットリロード相当）
npm run build    # tsc でビルド
npm start        # node でビルド済みを実行
```

## 6. 利用上の注意

1. 短時間の大量アクセスを避けること（KAKEN 利用規約）
2. APIで返る所属情報は採択時点のものであり、現在の所属とは異なる場合がある
3. 検索結果の二次利用には KAKEN の利用規約を確認すること

## 参考

- [KAKEN API 公式ドキュメント](https://support.nii.ac.jp/ja/kaken/api/api_outline)
- [パラメータ定義（bitbucket）](https://bitbucket.org/niijp/kaken_definition/)
- [CiNii API 利用登録](https://support.nii.ac.jp/ja/cinii/api/developer)
- [Model Context Protocol 仕様](https://modelcontextprotocol.io/)