asta-skill

Asta MCP：学術論文の検索

Asta は Ai2 の Scientific Corpus Tool です。Semantic Scholar の学術グラフを MCP（ストリーミング可能な HTTP）経由で利用できます。このスキルでは、エージェントがどのような意図に対してどの Asta ツールを呼び出すか、読みやすい範囲に応答を収める方法、そして気づきにくい失敗モードについて説明します。

• MCP エンドポイント： https://asta-tools.allen.ai/mcp/v1
• 認証： x-api-key ヘッダー（キーは https://share.hsforms.com/1L4hUh20oT3mu8iXJQMV77w3ioxm からリクエストしてください）
• トランスポート： ステートレスなストリーミング可能 HTTP（セッション ID なし、呼び出し間でサーバー側の状態を保持しません）
• 動作確認済み環境： Asta MCP サーバー v1.12.3、2026-10-01

前提条件の確認

ツールを呼び出す前に、ホストエージェントに Asta MCP サーバーが登録されていることを確認してください。ツール名には、インストール時に選択した MCP サーバー名が接頭辞として付与されます（通常は asta__<tool> または mcp__asta__<tool>）。

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

• Codex CLI：~/.codex/config.toml に [mcp_servers.asta] url = "https://asta-tools.allen.ai/mcp/v1" と env_http_headers = { "x-api-key" = "ASTA_API_KEY" } を追加します。
• 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	limit のデフォルトは 50。venues と publication_date_range に対応
既知の論文タイトル	search_paper_by_title	検索ではなく解決ツールです。最も一致する候補 1 件と matchScore を返します（limit を 5 にしても 1 行のみ返されます）。venues と publication_date_range に対応
既知の ID 1 件	get_paper	ID には接頭辞が必要です：DOI:、ARXIV:、PMID:、PMCID:、CorpusId:、MAG:、ACL:、URL:、または接頭辞なしの 40 桁の 16 進数の Semantic Scholar ID。接頭辞なしの arXiv ID（1706.03762）は Paper with id 1706.03762 not found で失敗します
既知の ID 複数件	get_paper_batch	ids は JSON の配列です。解決できない ID は通知なく除外されます（ID を 3 件指定して論文が 1 件返されても、エラーは発生しません）。返された paperIds と入力を照合してください
論文 X を引用した論文	get_citations	前方引用。limit のデフォルトは 100。publication_date_range に対応し、venues には対応していません。各行は {"citingPaper": {...}} でラップされています
名前から著者を検索	search_authors_by_name	fields のデフォルトは "name" で、name と authorId のみを返します。limit のデフォルトは 100
ある著者の出版物	get_author_papers	フィールドのパラメーター名は paper_fields です。limit のデフォルトは 1000 で、新しい順に返します。publication_date_range に対応し、venues には対応していません
X に言及する箇所	snippet_search	約 500 語の抜粋（タイトル／要約／本文。図表のキャプションと参考文献は除外）。limit のデフォルトは 20 で、各行のデータ量は大きく、limit より少ない行しか返されない場合があります。以下のパラメーターを参照してください

ツールごとにパラメーター名が異なります（不明なパラメーターは拒否されず、無視されます）

サーバーは不明な引数を黙って受け入れるため、パラメーター名を間違えると、フィルターされていない結果が正常に返されます。結果がフィルターされていないように見える場合は、コーパスを疑う前にパラメーター名を確認してください。

• get_author_papers では paper_fields でフィールドを選択します。fields= を渡しても無視され、タイトルのみが返されます。
• get_citations に venues はありません。venues= を渡しても無視され、引用元の行はフィルターされずに返されます。
• snippet_search には fields も publication_date_range もありません。使用できるのは、inserted_before（コーパスへの登録日。形式は YYYY-MM-DD／YYYY-MM／YYYY）、paper_ids（特定の論文にスニペットを絞り込むための、最大 100 件のカンマ区切り ID）、および venues です。
• fields／paper_fields パラメーターを持つツールはすべて、デフォルトで title を返します。パラメーターを省略すると、順位付けできず、読み取れない結果がひそかに返されます。
• どのツールも一致件数の合計は返しません。コーパス全体の件数ではなく、返された行数を報告してください。

行数とペイロードの上限（実測値）

呼び出し	行数	ペイロード
search_papers_by_relevance、limit=50、abstract を含むフルプリセット	50	約 296 KB（約 5.9 KB／行）
get_citations、デフォルトの limit=100、fields=title,year,venue	100	約 56 KB（約 0.6 KB／行）
get_paper、fields=title,year,citations（『Attention Is All You Need』）	1	約 200 KB
get_paper、fields=title,year,references（同じ論文、参考文献 41 件）	1	約 8 KB
get_author_papers、limit=100、paper_fields=title,year	87	約 33 KB（abstract がなくても約 0.4 KB／行）
search_authors_by_name、fields=name,paperCount,papers	著者 1 人	約 30 KB（その著者の論文 87 件すべて）
snippet_search、limit=2	スニペット 1 件	約 4.6 KB

• limit は必ず明示的に指定してください。論文と引用のリストでは 20～50、スニペットでは 5～10 が目安です。デフォルトの 50、100、1000 はコンテキストを圧迫します。
• snippet_search は、ドキュメントに記載されたデフォルト値と稼働中のサーバーの値が異なる唯一のツールです。公開されているドキュメントページには 250、稼働中のスキーマには 20 と記載されており、limit を設定しない場合は 20 行（約 85 KB）が実測されました。稼働中のスキーマを信頼し、limit を明示的に設定してください。
• get_paper／get_paper_batch で、fields を通じて citations や references を要求しないでください。被引用数の多い論文では、200 KB 以上が返されます。前方引用にはページネーションに対応した get_citations を使用してください。参考文献リストを取得する場合は、100 件未満と分かっている論文に限って references を要求してください。
• search_authors_by_name で papers を要求しないでください。著者の論文リスト全体が返され、limit は無視されます。代わりに、get_author_papers で limit を明示的に指定してください。
• 出力が表や順位付けの処理の場合は abstract を省略し、実際に説明する少数の論文に限って取得してください。

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

メタデータの検索：

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 を追加してください。

ドキュメントに記載されていないが機能するフィールド（そのまま渡されるフィールド）

externalIds、citationCount、influentialCitationCount はドキュメントのフィールド一覧にはありませんが、そのまま Semantic Scholar に渡され、正しく返されます（v1.12.3 で検証済み）。確認できた externalIds のキーは DOI、ArXiv、PubMed、PubMedCentral、CorpusId、MAG、DBLP です。注意点：

• すべての論文に DOI があるわけではありません。特に arXiv のプレプリントでは DOI がないことがあり、ArXiv と CorpusId のみの場合もあります。
• テストした ID（DOI:10.1038/s41586-021-03819-2、DOI:10.1101/...、DOI:10.1371/journal.pone.0000308）では DOI による検索が成功しましたが、ベストエフォートとして扱い、見つからない場合はタイトル検索と externalIds による検索に切り替えてください。
• get_paper は、要求しなくても paperId、isOpenAccess、openAccessPdf を返します。journal は {"pages": ...} のみの場合がよくあります。
• これらはすべてベストエフォートとして扱い、今後の Asta リリースで提供されなくなった場合は、適切に代替してください。

日付と会場のフィルター

publication_date_range は YYYY-MM-DD:YYYY-MM-DD を受け付けます。両端は省略でき、年または月の省略形も使用できます。例：2021:、:2015-01、2015:2020、2019-03。search_papers_by_relevance、search_paper_by_title、get_citations、get_author_papers で利用できます（get_author_papers で正しく動作することを検証済みです。2024:2024 を指定すると、87 件の論文を持つ著者から、期間内の論文がちょうど 7 件返されました）。

• 正確な日付が不明な論文でも year は保持されますが、publicationDate は null になります。不明な日付はその年の 1 月 1 日として扱われるため、年の境界でのフィルタリングは概算になります。
• venues は Semantic Scholar の会場名文字列に一致します。一般的な略称も解決されます（検証済み：NeurIPS と ICML はどちらも該当結果を返しました）。また、venue フィールドには正規の名称が返されます（Neural Information Processing Systems）。最も確実な方法は、まずフィルターなしでキーワード検索を行い、venue の値を確認してから、その文字列をそのまま指定して絞り込むことです。
• 一致する会場名文字列がない場合、エラーではなく 0 件が返されます。そのため、結果が空でも、論文が見つからないのではなく、会場名の文字列が間違っている可能性があります。

レスポンスの形式（検証済み）

paper (get_paper, get_paper_batch, search_*, get_author_papers, get_citations):
  paperId, externalIds{DOI?, ArXiv?, PubMed?, PubMedCentral?, CorpusId?, MAG?, DBLP?},
  title, venue, year, publicationDate?, abstract?, tldr{model, text},
  authors[{authorId, name}], journal{pages?}, citationCount?, influentialCitationCount?,
  isOpenAccess, openAccessPdf, fieldsOfStudy[]

citing row (get_citations):   {"citingPaper": {paperId, title, year, ...}}
author (search_authors_by_name):  authorId, name, affiliations[] (often empty), homepage?,
  paperCount?, citationCount?, hIndex?, externalIds{DBLP: ["Name"]}
snippet (snippet_search):  {"data":[{"score":0.77,
  "paper":{"corpusId":..., "title":..., "authors":["Name", ...], "openAccessInfo":{...}},
  "snippet":{"text":"..."}}], "retrievalVersion":...}

• authors は論文ツールではオブジェクトのリストですが、スニペット内では通常の文字列のリストです。
• スニペットの論文には paperId ではなく corpusId が含まれます。CorpusId:<corpusId> を指定して検索してください。
• search_paper_by_title は matchScore を追加で返します。値が高いほど一致度が高く、曖昧なタイトルを採用するか却下するかの判断に役立ちます。

ワークフローパターン

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

1. search_papers_by_relevance(keyword, publication_date_range="<current_year-5>:", fields="title,year,authors,venue,tldr,url,citationCount,influentialCitationCount", limit=20) を実行します。下限は今日の日付から計算します（2026 年の場合は 2021: を指定します）。ユーザーが古い研究を希望する場合は、フィルターを外すか範囲を広げます。
2. citationCount と新しさに基づいて上位 N 件を順位付けし、提示します。
3. 次の操作を提案します。最も影響力のある結果に対する get_citations、または特定の主張を調べる snippet_search。

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

1. get_paper(DOI|ARXIV|...) で起点となる論文を確認します。
2. get_citations(paperId, fields="title,year,venue,citationCount", limit=50) で、引用元をたどって展開します。
3. 必要に応じて、起点となる論文のタイトルの語句を使って search_papers_by_relevance を実行し、関連する別の論文を探します。
4. 提示する前に、paperId で重複を除去します。

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

1. search_authors_by_name(name, fields="name,affiliations,paperCount,citationCount,hIndex,externalIds", limit=10) を実行します。これらのフィールドは必ずリクエストしてください。デフォルトでは name と authorId しか返されません。externalIds.ORCID があれば、それで候補を判別し、続いて paperCount、citationCount、hIndex を確認します。リクエストしても affiliations は空であることがよくあります（検証済み）。判別の決め手として使うのは補助的な場合に限ります。名前の表記違いによって同一人物が別の ID に分かれることがあります（F. Theis と Fabian J. Theis は別々のプロフィールでした）。そのため、最初の行だけでなく上位数件の候補を確認してください。
2. get_author_papers(authorId, limit=50, paper_fields="title,year,authors,venue,tldr,url,citationCount", publication_date_range=?) で、新しい順に並んだ範囲指定済みの最初のページを取得します。
3. トピックのキーワードまたは日付で、クライアント側で絞り込みます。

パターン 4：根拠の取得

1. snippet_search(claim_query, limit=5) で、主張を述べている、または裏付けている箇所を検索します。
2. 特定の論文内で主張の根拠を確認するには、paper_ids="<id1>,<id2>,…"（≤100）を渡します。これにより、指定した論文だけを対象にスニペットが返されます。
3. 各結果について、get_paper("CorpusId:<corpusId>") で完全なメタデータを取得します。

出力とやり取りのルール

• 使用したツールと、返された行数を必ず報告します（合計件数を公開するツールはありません）。
• 最大 10 件の結果を表（タイトル、年、会場、取得済みの場合は引用数）で提示し、その後、特に関連性の高い数件の詳細を説明します。
• ユーザーが中国語で書いた場合は、中国語で要約を提示します。タイトルは原文のままにします。
• 結果の提示後、詳細 / 絞り込み / 引用 / スニペット / エクスポート / 完了を提案します。

Asta のレスポンスへの対処

状況	対処方法
結果に isError: true が含まれている	エラーは、HTTP ステータスが 200 のまま、isError: true とプレーンテキストのメッセージを含む通常の結果として返されます。そのため、転送ステータスを決して信用しないでください。例：無効なキーの場合は Error executing tool get_paper: HTTP status 403 Forbidden.、不明なツール名の場合は Unknown tool: get_references
content 配列が空	正当な空の結果です（たとえば、一致するものがない venues 文字列）。エラーではありません
ストリームに : ping のキープアライブだけが流れ、結果がない	結果がゼロ件のクエリで確認されています。サーバーは content: [] を返す代わりに、クライアントがタイムアウトするまで SSE ストリームを開いたままにする場合があります。クライアントにタイムアウトを設定し、1 回再試行してから「結果なし」と報告してください。無言でハングさせないでください
abstract が空	コーパス内のすべての論文に全文があるわけではありません。snippet_search にフォールバックするか、タイトルと tldr を提示してください
著者の曖昧さを解消できない	ランキングフィールドをあらかじめリクエストしてください（パターン 3）。まず externalIds.ORCID を優先し、次に paperCount／citationCount／hIndex を確認してください。affiliations は同点の場合にのみ使用してください
日付で絞り込んだ結果	publicationDate が null の場合でも、year は常に存在します。また、不明な日付は 1 月 1 日として扱われるため、年の境界における絞り込みは概算になります
429 Too Many Requests	順次 get_paper を呼び出す代わりに、待機時間を置き、get_paper_batch でまとめて処理してください
DOI／PubMed ID／arXiv ID が必要	fields に externalIds を追加してください。DOI がない場合は ArXiv にフォールバックしてください

重要なルール

• 個別の呼び出しを繰り返すより、意図をまとめてバッチ処理してください。 質問に独立した照会が 2 つ必要な場合は、順次ではなく、1 回のターンで並列に MCP 呼び出しを行ってください。
• ID を推測しないでください。 曖昧なタイトルはまず search_paper_by_title で検索し、ID には必ずプレフィックスを付けてください。
• コンテンツを読む前に isError を確認してください。 転送レベルのステータスは常に 200 です。
• レート制限を守ってください。 API キーを使うと上限は引き上げられますが、無制限にはなりません。ユーザーの依頼を超えて引用グラフを拡張しないでください。
• フィールドを捏造しないでください。 Asta が abstract、venue、citationCount に null を返した場合は、値を作り出さず、その旨を伝えてください。