NDL-MCP Pipeline

National Diet Library Model Context Protocol Integration

自然言語での書籍検索を可能にするMCPサーバー。国立国会図書館（NDL）の書誌データベースと Claude Desktop を繋ぎ、直感的な日本語クエリで学術資料を検索できます。

🎯 主な特徴

• 自然言語検索: 「沖縄の薬草に関する2015年以降の書籍」のような自然な表現で検索
• 階層的検索システム: ルールベース検索 + オプションでLLM強化（OpenAI API Key設定時）
• 図書館所蔵情報: オプションで全国の図書館の所蔵状況を取得
• 多様な検索手法: タイトル・件名・内容説明・著者での検索をサポート
• データ最適化: 95%以上のデータ削減で高速レスポンス
• Claude Desktop統合: MCP プロトコルによるシームレスなAI統合
• LLMオプショナル: OpenAI API未設定でもルールベース検索で完全動作

🚀 クイックスタート

1. インストール

git clone <repository-url>
cd ndl
npm install
npm run build

2. Claude Desktop設定

Claude Desktop設定ファイルを更新：

{
  "mcpServers": {
    "ndl-search": {
      "command": "/path/to/ndl/.mcp/run.sh"
    }
  }
}

3. 使用開始

Claude Desktopを再起動後、以下のように検索できます：

「聖徳太子に関する最新の研究書を5冊教えて」
「源氏物語の現代語訳で、角川書店から出版されたものを探して」
「茶道の月刊誌、2020年以降のものでお茶の水女子大学に所蔵されているものは？」

🔧 利用可能なツール

ndl_search_by_description (推奨)

内容・テーマベースの検索。最も関連性の高い結果を返します。

{
  description: "聖徳太子の政治思想と仏教的世界観の関係性",
  titleKeyword: "聖徳太子", // オプション
  maxRecords: 20,
  includeHoldings: false // 図書館所蔵情報を含めるか
}

ndl_search_by_subject

学術的な件名分類による検索。

{
  subject: "日本史",
  additionalSubject: "飛鳥時代", // オプション
  maxRecords: 20,
  includeHoldings: false
}

ndl_search_by_title

書名による検索。特定の本や版を探す際に最適。

{
  title: "源氏物語",
  additionalTitle: "現代語訳", // オプション
  maxRecords: 20,
  includeHoldings: false
}

ndl_search_books

総合検索。自然言語クエリをLLMで最適化。

{
  query: "沖縄の薬草に関する2015年以降の書籍",
  maxRecords: 20,
  preferLanguage: "jpn",
  includeHoldings: false
}

📊 検索結果フォーマット

{
  count: number,
  records: [
    {
      id: "ndl:023456789",
      title: "聖徳太子の政治思想",
      creators: ["山田太郎", "田中花子"],
      subjects: ["日本史", "古代史", "政治思想"],
      pub_date: "2023",
      identifiers: { NDLBibID: "023456789" },
      holdings?: [  // includeHoldings: true の場合のみ
        {
          libraryName: "国立国会図書館",
          libraryCode: "NDL",
          callNumber: "210.3/Y19",
          availability: "利用可",
          location: "本館一般資料室",
          opacUrl: "https://..."
        }
      ]
    }
  ],
  query: "subject=\"聖徳太子\"",
  formatted_records?: string  // output_format指定時
}

🎛️ 高度な機能

図書館所蔵情報

includeHoldings: true で全国の図書館の所蔵状況を取得：

// 注意：レスポンスサイズが大幅に増加します
await searchByDescription({
  description: "量子コンピューティング",
  includeHoldings: true
});

出力フォーマット

結果をYAMLやJSONで整形：

{
  description: "茶道の歴史",
  output_format: "yaml",  // または "json"
  maxRecords: 10
}

ランキングアルゴリズム

検索結果は以下の要素でスコアリング：

• 関連度: 検索語との一致度
• 学術性: 研究書・論文集の優遇
• 新しさ: 発行年による重み付け
• 網羅性: 全集・選集の優遇

🏗️ アーキテクチャ

自然言語クエリ
    ↓
QueryGenerator (LLM最適化)
    ↓
QueryValidator (安全性チェック)
    ↓
NDLConnector (SRU API)
    ↓
XMLMapper (データ変換)
    ↓
IntelligentFilter (スコアリング)
    ↓
MCPPublisher (Claude Desktop)

主要コンポーネント

• QueryGenerator: 自然言語→CQL変換
• IntelligentSearch: 階層的検索戦略
• XMLMapper: NDL XML→構造化データ
• RateLimit/Cache: パフォーマンス最適化
• DataFormatter: 出力フォーマット変換

🧪 テスト

# 全テスト実行
npm test

# カバレッジ付きテスト
npm run test:coverage

# E2Eテスト
npm run test:e2e

# 型チェック
npm run typecheck

# Lint
npm run lint

テストカバレッジ: 85%+ (ターゲット: 70%+)

🚦 開発サーバー

MCPサーバーモード

npm run mcp:server

HTTPサーバーモード

npm run http:server
# http://localhost:3000 でREST API利用可能

開発モード

npm run dev  # ホットリロード付き

📈 監視・メトリクス

ヘルスチェック

curl http://localhost:3000/healthz
curl http://localhost:3000/readyz

メトリクス

curl http://localhost:3000/metrics  # Prometheus形式

ログレベル

export LOG_LEVEL=debug  # debug, info, warn, error

🔧 設定

環境変数

# OpenAI API (オプション - 未設定時はルールベース)
OPENAI_API_KEY=sk-your-key-here

# ログレベル
LOG_LEVEL=info

# キャッシュ設定
CACHE_TTL_SECONDS=3600
CACHE_MAX_ITEMS=1000

# レート制限
RATE_LIMIT_REQUESTS=5
RATE_LIMIT_WINDOW_MINUTES=1

カスタマイズ可能な設定

• CQLクエリ生成ルール (config/LLM_PROMPT.json)
• XMLマッピングルール (docs/MAPPER_RULES.md)
• バリデーションルール (docs/VALIDATOR_RULES.md)

🛠️ トラブルシューティング

よくある問題

1. MCPツールが表示されない

# Claude Desktop設定確認
cat ~/Library/Application\ Support/Claude/claude_desktop_config.json

# プロジェクトパス確認
pwd  # /Users/kaz005/ndl

# Claude Desktop再起動

2. 検索結果が0件

# より広範な検索語を試す
"description" → "subject" → "title" の順で範囲を狭める

3. レスポンスが遅い

# キャッシュクリア
npm run cache:clear

# 図書館所蔵情報を無効化
includeHoldings: false

詳細なトラブルシューティング: README-MCP-SETUP.md

📚 関連ドキュメント

• 機能仕様
• API仕様
• テスト仕様
• マッピングルール
• MCP設定ガイド

🤝 コントリビューション

1. Fork the repository
2. Create feature branch (git checkout -b feature/amazing-feature)
3. Commit changes (git commit -m 'Add amazing feature')
4. Push to branch (git push origin feature/amazing-feature)
5. Open Pull Request

開発ガイドライン

• TDD (Test-Driven Development) 推奨
• カバレッジ 70%+ 必須
• TypeScript strict mode
• ESLint + Prettier

📄 ライセンス

MIT License - 詳細は LICENSE ファイルを参照

🙏 謝辞

• 国立国会図書館 - SRU API提供
• Model Context Protocol - 仕様策定
• Anthropic - Claude Desktop統合

📞 サポート

問題や質問がある場合は Issues で報告してください。

---

Version: 1.0.0
Node.js: 20.x+
TypeScript: 5.2+
License: MIT