asta-skill

Asta MCP — 学術論文検索

Asta は Ai2 の Scientific Corpus Tool であり、ストリーミング可能な HTTP トランスポートを介して Semantic Scholar の学術グラフを MCP に公開します。このスキルでは、エージェントが意図に応じてどの Asta ツールを呼び出すか、およびそれらを有用なワークフローに組み合わせる方法を説明します。

• MCP エンドポイント： https://asta-tools.allen.ai/mcp/v1
• 認証： x-api-key ヘッダー（https://share.hsforms.com/1L4hUh20oT3mu8iXJQMV77w3ioxm でキーをリクエストしてください）
• トランスポート： ストリーミング可能な HTTP

前提条件の確認

ツールを呼び出す前に、ホストエージェントに Asta MCP サーバーが登録されていることを確認してください。ツール名には、インストール時に選択した MCP サーバー名がプレフィックスとして付加されます（一般的には asta__<tool> または mcp__asta__<tool>）。

Asta のツールが表示されない場合は、生の HTTP 呼び出しを行ったり、結果を捏造したりしないでください。ユーザーに、https://asta-tools.allen.ai/mcp/v1 を x-api-key ヘッダー付きのストリーミング可能な HTTP MCP サーバーとして登録し、その後ホストを再起動または再読み込みするよう伝えてください。最小限のセットアップ方法：

• Codex CLI：[mcp_servers.asta] url = "https://asta-tools.allen.ai/mcp/v1" と env_http_headers = { "x-api-key" = "ASTA_API_KEY" } を ~/.codex/config.toml に追加します。
• Claude Code：claude mcp add -t http -s user asta https://asta-tools.allen.ai/mcp/v1 -H "x-api-key: $ASTA_API_KEY" を実行します。
• 汎用 MCP クライアント：サーバー URL https://asta-tools.allen.ai/mcp/v1 を、ヘッダー { "x-api-key": "<YOUR_API_KEY>" } とともに設定します。

ツールマップ — 意図 → Asta ツール

ユーザーの意図	Asta ツール	備考
幅広いトピックを検索する	search_papers_by_relevance	会議名と日付で絞り込み可能
論文のタイトルがわかっている	search_paper_by_title	venues と publication_date_range による絞り込みは任意
DOI／arXiv／PMID／CorpusId／MAG／ACL／SHA／URL がわかっている	get_paper	単一論文を検索
複数の ID がわかっている	get_paper_batch	バッチ検索。ids にはカンマ区切りの文字列ではなく JSON 配列 を渡します（snippet_search の paper_ids とは異なります）。get_paper を N 回連続して呼び出すより、こちらを優先してください。解決できない ID は黙って除外され（null／エラーは返されません）、入力と照合するには、返された paperId を確認してください
論文 X の引用元を調べる	get_citations	前方引用をページネーションで取得します。publication_date_range は受け付けますが、venues は受け付けません。limit のデフォルト値は 100 です
著者を名前で検索する	search_authors_by_name	デフォルトの fields="name" では name と authorId のみが返されます。順位付けに使える情報も取得するには、affiliations,paperCount,citationCount,hIndex,externalIds を明示的に指定してください。externalIds には ORCID／DBLP が含まれます（url／homepage も選択可能です）
著者の出版物を調べる	get_author_papers	著者 ID を渡します。フィールド指定パラメーターは fields ではなく paper_fields です。limit のデフォルト値は 1000 なので、明示的に設定してください
X に言及している箇所を探す	snippet_search	約 500 語の抜粋（タイトル／要旨／本文。図表のキャプションと参考文献は除く）を取得します。以下のスニペット固有のパラメーターを参照してください

ほとんどの検索／引用ツールは、publication_date_range（形式は YYYY-MM-DD:YYYY-MM-DD。"2021:"、":2015-01"、"2015:2020" のような年の省略記法も使用できます）、venues、およびフィールド選択用の fields を受け付けます。ユーザーの意図に範囲の指定がある場合（例：「最近の」「2022 年以降」「NeurIPS で」）は、これらを渡してください。venues は Semantic Scholar の完全一致する会議名に照合されます（例：カンマ区切りで "Nature,N. Engl. J. Med."）。「NeurIPS」のような一般的な名称では一致しない場合があるため、会議名での検索結果が空の場合は、日付やキーワードによる絞り込みに切り替えてください。

ツールごとのパラメーターの例外（稼働中のサーバーで確認済み。誤ると、不正な引数になったり、引数が黙って無視されたりします）：

• get_author_papers のフィールド選択パラメーター名は fields ではなく paper_fields です（fields= を渡すと黙って無視され、タイトルのみが返されます）。publication_date_range は受け付けますが、venues による絞り込みはできません。日付フィルターはページネーションの後に適用されるため、期間内の有効な論文が除外される場合があります（著名な著者に対する 2024:2024 の検索結果が [] になった例があります）。確実に結果を得るには、クライアント側でトピック／会議名と日付を使って絞り込んでください。
• get_citations は publication_date_range を受け付けますが、venues は受け付けません。
• snippet_search は fields と publication_date_range のどちらも受け付けません。代わりに、inserted_before（日付フィルター。YYYY-MM-DD／YYYY-MM／YYYY）、paper_ids（特定の論文のスニペットに限定する、100 件以下の ID のカンマ区切りリスト）、および venues を使用します。

⚠️ fields パラメーター — コンテキストの肥大化を避ける

get_paper / get_paper_batch は fields 文字列を受け付けます。fields で citations や references をリクエストしないでください。非常に多く引用されている論文（例：Attention Is All You Need）を1件取得するだけで、20万文字を超える結果が返され、エージェントのコンテキストウィンドウがあふれるおそれがあります。前方引用を取得するには、専用の get_citations ツールを使用してください（ページネーションに対応しています）。Asta には専用の get_references ツールがありません。論文の参考文献リストを取得するには、参照件数が少ないと分かっている論文（通常は100件未満）に限り、fields=references を指定して get_paper を使用してください。

行数にも注意してください。行ごとのサイズだけでなく、件数も確認しましょう。デフォルトの limit は大きく、get_author_papers は最大 1000 件、get_citations は 100 件、search_papers_by_relevance は 50 件、snippet_search は 20 件を返します（各スニペットは約500語で、行あたりの負荷が最も大きいツールです）。ユーザーが全件を求めている場合を除き、明示的に小さい limit を指定してください。たとえば、論文や引用のリストでは20～50件、スニペットでは約5～10件にします。

タスクに応じたフィールドのプリセットを使用してください。

メタデータの検索：

title,year,authors,venue,tldr,url,abstract

検索・ランキング・結果テーブル：

title,year,authors,venue,tldr,url,abstract,citationCount,influentialCitationCount

DOI／エクスポートへの引き渡し：

title,year,authors,venue,tldr,url,externalIds

journal、publicationDate、fieldsOfStudy、isOpenAccess は、必要な場合にのみ追加してください。将来のレスポンスに citationCount などのパススルーフィールドが含まれない場合は、適切に対応し、関連性／新しさで並べ替えて、引用数に基づく主張は省略してください。

呼び出し例（トピック検索、引用数順にランキングし、後続の取得に使う DOI を表示）：

search_papers_by_relevance(
  keyword="mixture of experts routing",
  publication_date_range="2023:",
  fields="title,year,authors,venue,tldr,url,externalIds,citationCount",
  limit=20,
)

DOI／外部 ID の取得（未文書化ですがサポートされています）

Asta の公式な fields リストに externalIds は含まれていませんが、このフィールドは基盤の Semantic Scholar API に透過的に渡されるため、実際に使用できます。fields に externalIds を追加すると、DOI、PubMed、PubMedCentral、ArXiv、MAG、DBLP、CorpusId を取得できます。同じパススルーは citationCount と influentialCitationCount にも適用されます（どちらも公式リストにはありませんが、返されることを確認済みです）。引用数で結果をランキングする場合は、これらをリクエストしてください。注意事項：

• すべての論文に DOI があるわけではありません。arXiv のみのプレプリントでは、多くの場合 ArXiv と CorpusId だけが返されます。
• get_paper("DOI:...") による検索の信頼性は完全ではなく、有効な DOI でも not found が返される場合があります。まずタイトルで検索し、結果から externalIds を取得してください。
• これは未文書化の機能なので、ベストエフォートとして扱い、将来の Asta リリースで削除された場合にも適切に対応してください。

ワークフローのパターン

パターン 1 — トピックの探索

1. search_papers_by_relevance(keyword, publication_date_range="<current_year-5>:", venues=?, fields="title,year,authors,venue,tldr,url,abstract,citationCount,influentialCitationCount", limit=20) → 最初の検索結果を取得します（下限は今日の日付から計算します。たとえば2026年には publication_date_range="2021:" を渡します。ユーザーが古い研究を求めている場合は、フィルターを調整するか削除してください）。
2. citationCount と新しさに基づいて上位 N 件をランキングし、提示します。
3. フォローアップとして、最も影響力のある論文に対する get_citations、または特定の主張を検索する snippet_search を提案します。

パターン 2 — 起点となる論文からの展開

1. get_paper(DOI|arXiv|...) → 起点となる論文を確認します。
2. get_citations(paperId) → 前方へ展開します。
3. 必要に応じて、起点の論文タイトルに含まれる語句を使って search_papers_by_relevance を実行し、周辺の論文を探索します。
4. 提示する前に、paperId で重複を除外します。

パターン 3 — 著者の詳細調査

1. search_authors_by_name(name, fields="name,affiliations,paperCount,citationCount,hIndex,externalIds") → 適切なプロフィールを選びます。これらのフィールドを必ずリクエストしてください。デフォルトの fields="name" では name と authorId しか返されず、ランキングに使える情報がありません。該当する場合は externalIds.ORCID（最も確かな手掛かり）で識別し、次に paperCount／citationCount／hIndex を使います。リクエストしても affiliations が空の場合が多いため、同点の場合の判断材料としてのみ使用してください。
2. get_author_papers(authorId, limit=50, paper_fields="title,year,authors,venue,tldr,url,abstract,citationCount") → 上限を設けた最初のページを取得します。ユーザーが全件を求めた場合にのみ、取得範囲を広げてください。
3. クライアント側でトピックのキーワードまたは日付を基準に絞り込みます。

パターン 4 — エビデンスの取得

1. snippet_search(claim_query) → 主張を述べている、または裏付けている箇所を見つけます
2. 特定の論文内で主張を裏付けるには、paper_ids="<id1>,<id2>,…"（≤100）を渡すと、そのセットのみからスニペットが取得されます
3. 各検索結果について、必要に応じて get_paper(id) で完全なメタデータを取得します

出力と対話のルール

• 使用したツールを必ず報告します。合計件数を報告するのは、ツールが合計を返す場合のみです。それ以外の場合は、返された件数またはページサイズを報告し、コーパス全体の件数であるかのように示してはいけません。
• 最大10件の検索結果を表（タイトル、年、会場、取得した場合は引用数）で提示し、その後、最も関連性の高い結果の詳細を示します。
• ユーザーが中国語で書いた場合、要約は中国語で提示し、タイトルは原文のままにします。
• 検索結果の提示後、詳細 / 絞り込み / 引用 / スニペット / エクスポート / 完了を提案します。

重要なルール

• 逐次的なやり取りより、一括での意図に沿った処理を優先します。 ユーザーの質問に独立した検索が2つ必要な場合は、逐次実行せず、1ターン内で並列に MCP ツールを呼び出します。
• IDを推測してはいけません。 ユーザーが曖昧なタイトルを示した場合は、get_paper の前に search_paper_by_title を使用します。
• レート制限を守ります。 API キーで上限は引き上げられますが、無制限になるわけではありません。ユーザーが求めた範囲を超えて引用グラフの展開を続けてはいけません。
• フィールドを捏造してはいけません。 Asta が abstract または venue を null で返した場合は、創作せず、その旨を伝えます。

Asta の応答への対処

状況	対応
abstract が空	コーパス内のすべての論文に全文があるわけではありません。snippet_search を使用するか、タイトルと TLDR に切り替えます
著者の曖昧性解消が不確実	先にランキングフィールドを指定するよう依頼します（パターン 3 を参照。デフォルトでは返されません）。externalIds.ORCID を優先し、次に paperCount／citationCount／hIndex を使用します。affiliations は同点の場合の判断材料としてのみ使用します
日付で絞り込んだ結果	publication_date_range フィルターでは、publicationDate が null のレコードが返されることがあります（保証されるのは year のみです）。また、日付不明の論文はその年の1月1日に公開されたものとして扱われるため、境界年の絞り込みは概算になります
429 Too Many Requests	バックオフし、get_paper を逐次呼び出す代わりに get_paper_batch でまとめて取得します
DOI／PubMed ID／arXiv ID が必要	fields に externalIds を追加します（上記「DOI の取得」を参照）。DOI がない場合は ArXiv ID を使用します