Semanticscholarmcp

🚀 Semantic Scholar MCP Server

このサーバーは、Semantic Scholar Academic Graph APIにアクセスできるModel Context Protocol (MCP)サーバーです。学術論文や著者を検索し、引用や参考文献に関する詳細情報を取得できます。

✨ 主な機能

• 論文検索：様々なフィルターを使って学術論文を検索できます。
• 論文詳細：特定の論文に関する詳細情報を取得できます。
• 一括論文取得：一度に複数の論文の情報を取得できます。
• 著者検索：名前で著者を検索できます。
• 著者詳細：特定の著者に関する詳細情報とその論文を取得できます。
• 引用分析：特定の論文を引用している論文を取得できます。
• 参考文献分析：特定の論文が引用している論文を取得できます。
• 引用文脈：ある論文が別の論文を引用する文脈を取得できます。
• テキストスニペット：学術論文全体でテキストスニペットを検索できます。
• PDFダウンロード：適切なファイル名とメタデータでオープンアクセスのPDFをダウンロードできます。
• PDF利用可能性：ダウンロード前にPDFが利用可能かどうかを確認できます。
• スマートな命名：論文のタイトルと年をファイル名としてPDFを保存します。
• メタデータサポート：PDFファイルのプロパティにタイトル、著者、年を埋め込みます。

📦 インストール

1. このリポジトリをクローンします：

git clone <repository-url>
cd SemanticScholarMCP

2. 依存関係をインストールします：

pip install -r requirements.txt

3. （オプションだが推奨）Semantic Scholar APIキーを設定します：

export SEMANTIC_SCHOLAR_API_KEY="your-api-key-here"

注意：APIキーはオプションです。APIキーなしでもサーバーは動作しますが、すべての未認証ユーザーで共有されるパブリックなレート制限（1秒あたり1000リクエスト）が適用されます。

4. （オプション）PDFメタデータサポートをインストールします：

pip install -e ".[metadata]"

🚧 開発

開発環境のセットアップ

# 開発用の依存関係を含めてインストール
pip install -e ".[test,dev]"

テストの実行

# すべてのテストを実行
make test

# 単体テストのみを実行（高速、API呼び出しなし）
make test-unit

# 統合テストを実行（APIキーが必要）
export SEMANTIC_SCHOLAR_API_KEY="your-api-key"
make test-integration

# パフォーマンステストを実行
make test-performance

コード品質

# リントを実行
make lint

# コードをフォーマット
make format

⚙️ 設定

このサーバーをMCPクライアントの設定に追加します：

{
  "mcpServers": {
    "SemanticScholarMCP": {
      "command": "/Users/your-username/Desktop/SemanticScholarMCP/venv/bin/python",
      "args": ["/Users/your-username/Desktop/SemanticScholarMCP/src/semantic_scholar_mcp/server.py"],
      "env": {
        "SEMANTIC_SCHOLAR_API_KEY": "your-actual-api-key-here"
      }
    }
  }
}

APIキーなしの設定（パブリックなレート制限を共有）：

{
  "mcpServers": {
    "SemanticScholarMCP": {
      "command": "/Users/your-username/Desktop/SemanticScholarMCP/venv/bin/python",
      "args": ["/Users/your-username/Desktop/SemanticScholarMCP/src/semantic_scholar_mcp/server.py"]
    }
  }
}

重要：

• your-usernameを実際のユーザー名に置き換えてください。
• APIキーはオプションですが、専用のレート制限を利用するために推奨されます。
• APIキーなしの場合：すべてのユーザーで共有されるパブリックなレート制限（1秒あたり1000リクエスト）が適用されます。
• 無料のAPIキーを使用する場合：あなたの使用に対して専用のより高いレート制限が適用されます。

🛠️ 利用可能なツール

論文関連ツール

search_papers

様々なフィルターを使って学術論文を検索します。

パラメーター：

• query（必須）：検索クエリ文字列
• limit：最大結果数（デフォルト：10、最大：100）
• offset：スキップする結果数（デフォルト：0）
• fields：返すフィールドのカンマ区切りリスト
• publication_types：出版タイプでフィルタリング
• open_access_pdf：オープンアクセスのPDFを持つ論文でフィルタリング
• min_citation_count：最小引用数
• year：出版年または年の範囲（例："2020 - 2023"）
• venue：出版場所

get_paper

特定の論文に関する詳細情報を取得します。

パラメーター：

• paper_id（必須）：論文ID（Semantic Scholar ID、DOI、ArXiv IDなど）
• fields：返すフィールドのカンマ区切りリスト

get_paper_batch

一度のリクエストで複数の論文の情報を取得します。

パラメーター：

• paper_ids（必須）：論文IDのカンマ区切りリスト
• fields：返すフィールドのカンマ区切りリスト

著者関連ツール

search_authors

名前で著者を検索します。

パラメーター：

• query（必須）：著者名または検索クエリ
• limit：最大結果数（デフォルト：10、最大：1000）
• offset：スキップする結果数（デフォルト：0）
• fields：返すフィールドのカンマ区切りリスト

get_author

特定の著者に関する詳細情報を取得します。

パラメーター：

• author_id（必須）：著者ID
• fields：返すフィールドのカンマ区切りリスト

引用と参考文献関連ツール

get_paper_citations

特定の論文を引用している論文を取得します。

パラメーター：

• paper_id（必須）：引用を取得する論文ID
• limit：最大結果数（デフォルト：10、最大：1000）
• offset：スキップする結果数（デフォルト：0）
• fields：返すフィールドのカンマ区切りリスト

get_paper_references

特定の論文が引用している論文を取得します。

パラメーター：

• paper_id（必須）：参考文献を取得する論文ID
• limit：最大結果数（デフォルト：10、最大：1000）
• offset：スキップする結果数（デフォルト：0）
• fields：返すフィールドのカンマ区切りリスト

get_citation_context

ある論文が別の論文を引用する文脈を取得します。

パラメーター：

• paper_id（必須）：引用される論文のID
• citing_paper_id（必須）：引用する論文のID

テキスト検索関連ツール

search_snippets

学術論文全体でテキストスニペットを検索します。

パラメーター：

• query（必須）：テキストスニペットの検索クエリ
• limit：最大結果数（デフォルト：10、最大：100）
• offset：スキップする結果数（デフォルト：0）

PDF関連ツール

get_paper_pdf_info

論文のPDFの利用可能性を確認します。

パラメーター：

• paper_id（必須）：PDFの利用可能性を確認する論文ID

download_paper_pdf

利用可能な場合、論文のPDFをダウンロードし、論文のタイトルをファイル名としてメタデータを設定します。

パラメーター：

• paper_id（必須）：PDFをダウンロードする論文ID
• download_path：PDFを保存するディレクトリ（デフォルト：~/Downloads/semantic_scholar_papers）

特徴：

• 論文のタイトルをファイル名として使用します（例："Machine Learning in Healthcare (2023).pdf"）
• タイトル、著者、出版年をPDFのメタデータに設定します
• 重複するファイル名を自動的に処理します
• 整理されたフォルダ構造を作成します

💻 使用例

機械学習に関する論文を検索

search_papers("machine learning", limit=5, year="2023")

特定の論文の詳細を取得

get_paper("10.1038/nature14539")

特定の論文を引用している論文を検索

get_paper_citations("10.1038/nature14539", limit=10)

著者を検索

search_authors("Geoffrey Hinton")

引用文脈を取得

get_citation_context("paper-id-1", "paper-id-2")

PDFの利用可能性を確認

get_paper_pdf_info("10.1038/nature14539")

論文のPDFをダウンロード

download_paper_pdf("10.1038/nature14539")

これにより、PDFは次のような名前で保存されます：

"Deep learning (2015).pdf"

タイトル、著者（LeCun, Y., Bengio, Y., Hinton, G.）、年（2015）を含むメタデータが埋め込まれます。

🚧 APIのレート制限

Semantic Scholar APIには次のレート制限があります：

• APIキーなし：すべての未認証ユーザーで共有される1秒あたり1000リクエスト（高負荷時には制限される場合があります）
• 無料のAPIキーあり：個人の使用に対して専用のより高いレート制限が適用されます。

安定したパフォーマンスを得るために、無料のAPIキーを取得することをおすすめします。

🐞 トラブルシューティング

レート制限エラー

次のエラーが表示された場合：

Error: Rate limit exceeded. Please wait a moment and try again, or get an API key for higher limits.

これは、共有されるパブリックなレート制限に達したか、高負荷によりAPIが制限されていることを意味します。

即時解決策：

1. 無料のAPIキーを取得（推奨）：
   • https://www.semanticscholar.org/product/apiにアクセスします。
   • 無料アカウントを登録します。
   • APIキーを取得します。
   • Claude Desktopの設定に追加します：

   "env": {
     "SEMANTIC_SCHOLAR_API_KEY": "your-actual-api-key-here"
   }
   

   • Claude Desktopを再起動します。
2. 待機して再試行：共有されるパブリックなレート制限が一時的に超過されている可能性があります。
3. 結果の制限を小さくする：クエリのlimitパラメーターを減らします。
4. リクエストを分散する：短時間に多数のリクエストを行わないようにします。

設定問題

• 設定内のPythonパスが正しい仮想環境を指していることを確認します。
• サーバースクリプトのパスが正しいことを確認します。
• 仮想環境にすべての依存関係がインストールされていることを確認します。

接続のテスト

Claudeに小さい制限で単一の論文を検索するように依頼することで、サーバーが正常に動作しているかテストできます：

search_papers("machine learning", limit=1)

⚠️ エラーハンドリング

すべてのツールには包括的なエラーハンドリングが含まれており、リクエストが失敗した場合やAPIがエラーを返した場合には、説明的なエラーメッセージが返されます。

📄 ライセンス

このプロジェクトはMITライセンスの下でライセンスされています。詳細はLICENSEファイルを参照してください。

👥 コントリビューション

コントリビューションは大歓迎です！ご自由にプルリクエストを送信してください。