Open Alex MCP

OpenAlex.org API を使用して、著者名の曖昧性解消と学術研究を行う、簡潔な Model Context Protocol（MCP）サーバーです。最適化されたデータ構造と拡張機能により、AI エージェント向けに特化して設計されています。

---

🎯 主な機能

🔍 コア機能

• 高度な著者名の曖昧性解消：複雑なキャリアの変遷や名前の異表記に対応します
• 所属機関の解決：変遷の追跡を含む、現在および過去の所属機関を確認します
• 学術論文の取得：学術誌の記事、書簡、研究論文を取得します
• 引用分析：h-index、引用数、影響度指標を確認します
• ORCID との統合：ORCID 識別子を使用した、最も高精度なマッチングを実現します

🚀 AI エージェント向けに最適化

• 簡潔なデータ：曖昧性解消に不可欠な情報に焦点を当てています
• 高速処理：迅速な分析のためにデータ構造を最適化しています
• スマートなフィルタリング：対象を絞ったクエリに対応する、拡張されたフィルタリングオプションを提供します
• 整理された出力：AI の推論に最適化された、構造化された応答を返します

🤖 エージェントとの統合

• 複数の候補：自動意思決定に使える、順位付けされた結果を返します
• 構造化された応答：LLM 向けに最適化された、解析しやすい出力を返します
• エラー処理：わかりやすいメッセージとともに、適切に機能を縮退させます
• 拡張されたフィルタリング：学術誌のみ、引用数のしきい値、期間フィルターに対応します

🏛️ プロフェッショナル品質

• MCP のベストプラクティス：公式ガイドラインに従い、FastMCP で構築しています
• ツールの注釈：クライアントとの最適な統合に向け、適切な MCP ツール注釈を設定しています
• リソース管理：HTTP クライアントの管理とクリーンアップを効率的に行います
• レート制限：適切な間隔を設け、API を節度をもって利用します

---

🚀 クイックスタート

前提条件

• Python 3.10 以降
• MCP 対応クライアント（例：Claude Desktop）
• メールアドレス（OpenAlex API を利用する際の配慮として）

インストール

詳しいインストール手順については、INSTALL.md を参照してください。

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

   git clone https://github.com/drAbreu/alex-mcp.git
   cd alex-mcp
   

2. 仮想環境を作成します：

   python3 -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   

3. パッケージをインストールします：

   pip install -e .
   

4. 環境を設定します：

   export [email protected]
   

5. サーバーを実行します：

   ./run_alex_mcp.sh
   # Or, if installed as a CLI tool:
   alex-mcp
   

---

⚙️ MCP の設定

Claude Desktop の設定

Claude Desktop の設定ファイルに追加します：

{
  "mcpServers": {
    "alex-mcp": {
      "command": "/path/to/alex-mcp/run_alex_mcp.sh",
      "env": {
        "OPENALEX_MAILTO": "[email protected]"
      }
    }
  }
}

/path/to/alex-mcp を、お使いのシステム上のリポジトリの実際のパスに置き換えてください。

---

🤖 AI エージェントでの使用

OpenAI エージェントとの統合

agents.mcp.MCPServerStdio インターフェースを使用して、OpenAI エージェントのワークフローにこの MCP サーバーを読み込めます：

from agents.mcp import MCPServerStdio

async with MCPServerStdio(
    name="OpenAlex MCP For Author disambiguation and works",
    cache_tools_list=True,
    params={
        "command": "uvx",
        "args": [
            "--from", "git+https://github.com/drAbreu/[email protected]",
            "alex-mcp"
        ],
        "env": {
            "OPENALEX_MAILTO": "[email protected]"
        }
    },
    client_session_timeout_seconds=10
) as alex_mcp:
    await alex_mcp.connect()
    tools = await alex_mcp.list_tools()
    print(f"Available tools: {[tool.name for tool in tools]}")

学術研究エージェントとの統合

この MCP サーバーは、学術研究のワークフローに特化して最適化されています：

# Optimized for academic research workflows
from alex_agent import run_author_research

# Enhanced functionality with streamlined data
result = await run_author_research(
    "Find J. Abreu at EMBO with recent publications"
)

# Clean, structured output for AI processing
print(f"Success: {result['workflow_metadata']['success']}")
print(f"Quality: {result['research_result']['metadata']['result_analysis']['quality_score']}/100")

uvx で直接起動

# Standard launch
uvx --from git+https://github.com/drAbreu/[email protected] alex-mcp

# With environment variables
[email protected] uvx --from git+https://github.com/drAbreu/[email protected] alex-mcp

---

🛠️ 利用可能なツール

1. autocomplete_authors ⭐ NEW

OpenAlex のオートコンプリート API を使用して、複数の著者候補を取得し、インテリジェントな曖昧性解消を行います。

パラメーター：

• name（必須）：検索する著者名（例：「James Briscoe」、「M. Ralser」）
• context（任意）：曖昧性解消のためのコンテキスト（例：「Francis Crick Institute の発生生物学」）
• limit（任意）：候補の最大数（1～10、デフォルト：5）

主な機能：

• ⚡ 高速：応答時間は約200ミリ秒
• 🎯 スマート：所属機関のヒント付きで複数の候補を提示
• 🧠 AI 対応：コンテキストに基づく選択に最適
• 📊 豊富な情報：論文数、引用数、所属機関の情報

簡潔な出力：

{
  "query": "James Briscoe",
  "context": "Francis Crick Institute",
  "total_candidates": 3,
  "candidates": [
    {
      "openalex_id": "https://openalex.org/A5019391436",
      "display_name": "James Briscoe",
      "institution_hint": "The Francis Crick Institute, UK",
      "works_count": 415,
      "cited_by_count": 24623,
      "external_id": "https://orcid.org/0000-0002-1020-5240"
    }
  ]
}

使用パターン：

# Get multiple candidates for disambiguation
candidates = await autocomplete_authors(
    "James Briscoe", 
    context="Francis Crick Institute developmental biology"
)

# AI selects best match based on institutional context
# Much more accurate than single search result!

2. search_authors

AI エージェント向けに簡潔な出力で著者を検索します。

パラメーター：

• name（必須）：検索する著者名
• institution（任意）：所属機関名によるフィルター
• topic（任意）：研究トピックによるフィルター
• country_code（任意）：国コードによるフィルター（例：「US」、「DE」）
• limit（任意）：結果の最大数（1～25、デフォルト：20）

簡潔な出力：

{
  "query": "J. Abreu",
  "total_count": 3,
  "results": [
    {
      "id": "https://openalex.org/A123456789",
      "display_name": "Jorge Abreu-Vicente",
      "orcid": "https://orcid.org/0000-0000-0000-0000",
      "display_name_alternatives": ["J. Abreu-Vicente", "Jorge Abreu Vicente"],
      "affiliations": [
        {
          "institution": {
            "display_name": "European Molecular Biology Organization",
            "country_code": "DE"
          },
          "years": [2023, 2024, 2025]
        }
      ],
      "cited_by_count": 316,
      "works_count": 25,
      "summary_stats": {
        "h_index": 9,
        "i10_index": 5
      },
      "x_concepts": [
        {
          "display_name": "Astrophysics",
          "score": 0.8
        },
        {
          "display_name": "Machine Learning", 
          "score": 0.6
        }
      ]
    }
  ]
}

機能：AI による推論と曖昧性解消に最適化された、明快な構造

---

2. retrieve_author_works

強化されたフィルタリング機能を使用して、指定した著者の論文を取得します。

パラメーター：

• author_id（必須）：OpenAlex の著者 ID
• limit（任意）：結果の最大数（1～50、デフォルト：20）
• order_by（任意）：「date」または「citations」（デフォルト：「date」）
• publication_year（任意）：特定の年でフィルター
• type（任意）：論文の種類によるフィルター（例：「journal-article」）
• authorships_institutions_id（任意）：所属機関によるフィルター
• is_retracted（任意）：撤回された論文でフィルター
• open_access_is_oa（任意）：オープンアクセスの状態でフィルター

強化された出力：

{
  "author_id": "https://openalex.org/A123456789",
  "total_count": 25,
  "results": [
    {
      "id": "https://openalex.org/W123456789",
      "title": "A platform for the biomedical application of large language models",
      "doi": "10.1038/s41587-024-02534-3",
      "publication_year": 2025,
      "type": "journal-article",
      "cited_by_count": 42,
      "authorships": [
        {
          "author": {
            "display_name": "Jorge Abreu-Vicente"
          },
          "institutions": [
            {
              "display_name": "European Molecular Biology Organization"
            }
          ]
        }
      ],
      "locations": [
        {
          "source": {
            "display_name": "Nature Biotechnology",
            "type": "journal"
          }
        }
      ],
      "open_access": {
        "is_oa": true
      },
      "primary_topic": {
        "display_name": "Biomedical Engineering"
      }
    }
  ]
}

機能：柔軟なフィルタリングに対応した包括的な論文データにより、対象を絞った検索が可能です

---

📊 データの最適化

焦点を絞った情報設計

この MCP サーバーは、AI エージェントが利用しやすいよう特別に設計された、焦点の明確な構造化データを提供します。

著者データの機能

• 本人確認：曖昧性解消のための氏名、ORCID、別名
• 所属の追跡：現在および過去の所属機関とのつながり
• 影響度指標：引用数、h-index、学術的な影響度
• 研究コンテキスト：分野、概念、専門領域
• キャリア分析：所属機関の変遷と異動の時系列分析

論文データの機能

• 出版メタデータ：タイトル、DOI、掲載先、出版情報
• 影響度評価：引用数と学術的影響力
• アクセス情報：オープンアクセスの状態と利用可能性
• 著者情報：著者の全リストと所属機関
• 研究分類：トピック、概念、分野分類

強化されたフィルタリング

# Target high-impact journal articles
works = await retrieve_author_works(
    author_id="https://openalex.org/A123456789",
    type="journal-article",      # Focus on journal publications
    open_access_is_oa=True,      # Open access only
    order_by="citations",        # Most cited first
    limit=15
)

# Career transition analysis
authors = await search_authors(
    name="J. Abreu",
    institution="EMBO",          # Current institution
    topic="Machine Learning",    # Research focus
    limit=10
)

---

🧪 使用例

著者の曖昧性解消

from alex_mcp.server import search_authors_core

# Comprehensive author search
results = search_authors_core(
    name="J Abreu Vicente",
    institution="EMBO",
    topic="Machine Learning",
    limit=20
)

print(f"Found {results.total_count} candidates")
for author in results.results:
    print(f"- {author.display_name}")
    if author.affiliations:
        current_inst = author.affiliations[0].institution.display_name
        print(f"  Institution: {current_inst}")
    print(f"  Metrics: {author.cited_by_count} citations, h-index {author.summary_stats.h_index}")
    if author.x_concepts:
        fields = [c.display_name for c in author.x_concepts[:3]]
        print(f"  Research: {', '.join(fields)}")

学術論文の分析

from alex_mcp.server import retrieve_author_works_core

# Comprehensive work retrieval
works = retrieve_author_works_core(
    author_id="https://openalex.org/A5058921480",
    type="journal-article",      # Academic focus
    order_by="citations",        # Impact-based ordering
    limit=20
)

print(f"Found {works.total_count} publications")
for work in works.results:
    print(f"- {work.title}")
    if work.locations:
        journal = work.locations[0].source.display_name
        print(f"  Published in: {journal} ({work.publication_year})")
    print(f"  Impact: {work.cited_by_count} citations")
    if work.open_access and work.open_access.is_oa:
        print("  ✓ Open Access")

機関と分野の分析

# Analyze career transitions
def analyze_career_path(author_result):
    affiliations = author_result.affiliations
    if len(affiliations) > 1:
        print("Career path:")
        for aff in sorted(affiliations, key=lambda x: min(x.years)):
            years = f"{min(aff.years)}-{max(aff.years)}"
            print(f"  {years}: {aff.institution.display_name}")
    
    # Research evolution
    if author_result.x_concepts:
        print("Research areas:")
        for concept in author_result.x_concepts[:5]:
            print(f"  {concept.display_name} (score: {concept.score:.2f})")

# Usage
results = search_authors_core("Jorge Abreu Vicente")
if results.results:
    analyze_career_path(results.results[0])

---

🔧 設定オプション

環境変数

# Required
export [email protected]

# Optional settings
export OPENALEX_MAX_AUTHORS=100             # Maximum authors per query
export OPENALEX_USER_AGENT=research-agent-v1.0
export ALEX_MCP_VERSION=4.1.0

# Rate limiting (respectful usage)
export OPENALEX_RATE_PER_SEC=10
export OPENALEX_RATE_PER_DAY=100000

パフォーマンスの調整

# For comprehensive research applications
config = {
    "max_authors_per_query": 25,     # Detailed author analysis
    "max_works_per_author": 50,      # Complete publication history
    "enable_all_filters": True,      # Full filtering capabilities
    "detailed_affiliations": True,   # Complete institutional data
    "research_concepts": True        # Detailed concept analysis
}

---

🧑‍💻 開発とテスト

プロジェクト構成

alex-mcp/
├── src/alex_mcp/
│   ├── server.py              # Main MCP server
│   ├── data_objects.py        # Data models and structures
│   └── utils.py               # Utility functions
├── examples/
│   ├── basic_usage.py         # Simple examples
│   ├── advanced_queries.py    # Complex query examples
│   └── integration_demo.py    # AI agent integration
├── tests/
│   ├── test_server.py         # Server functionality tests
│   └── test_integration.py    # Integration tests
└── docs/
    └── api_reference.md       # Detailed API documentation

テストの実行

# Install test dependencies
pip install -e ".[test]"

# Run functionality tests
pytest tests/test_server.py -v

# Test with real queries
python examples/basic_usage.py

# Test AI agent integration
python examples/integration_demo.py

開発例

# Test author disambiguation
python examples/basic_usage.py --query "J. Abreu" --institution "EMBO"

# Test work retrieval
python examples/advanced_queries.py --author-id "A123456789" --type "journal-article"

# Test integration patterns
python examples/integration_demo.py --workflow "career-analysis"

---

📈 統合例

学術研究のワークフロー

AI を活用した研究分析とシームレスに統合できます。

# Enhanced academic research agent
from alex_agent import AcademicResearchAgent

agent = AcademicResearchAgent(
    mcp_servers=[alex_mcp],  # Streamlined data processing
    model="gpt-4.1-2025-04-14"
)

# Complex research queries with structured data
result = await agent.research_author(
    "Find J. Abreu at EMBO with machine learning publications"
)

# Rich, structured output for AI reasoning
print(f"Quality Score: {result.quality_score}/100")
print(f"Author disambiguation: {result.confidence}")
print(f"Research fields: {result.research_domains}")

マルチエージェントシステム

# Collaborative research analysis
async def research_collaboration_network(seed_author):
    # Find primary author
    authors = await alex_mcp.search_authors(seed_author)
    primary = authors['results'][0]
    
    # Get their works
    works = await alex_mcp.retrieve_author_works(
        primary['id'], 
        type="journal-article"
    )
    
    # Analyze co-authors and build network
    collaborators = set()
    for work in works['results']:
        for authorship in work.get('authorships', []):
            collaborators.add(authorship['author']['display_name'])
    
    return {
        'primary_author': primary,
        'publication_count': len(works['results']),
        'collaborator_network': list(collaborators),
        'research_impact': sum(w['cited_by_count'] for w in works['results'])
    }

---

🤝 貢献

機能の改善や新機能の追加に向けた貢献を歓迎します。

1. リポジトリをフォークする
2. 機能ブランチを作成する：git checkout -b feature/enhanced-filtering
3. テストを追加する：変更によってデータの品質と構造が維持されることを確認します
4. プルリクエストを送信する：使用例とドキュメントを含めてください

開発の優先事項

• フィルタリング機能の強化
• データエンリッチメントの追加
• パフォーマンスの最適化
• 統合例の追加
• ドキュメントの改善

---

📄 ライセンス

このプロジェクトは MIT ライセンスの下で公開されています。詳細は LICENSE をご覧ください。

---

🌐 リンク

• OpenAlex API ドキュメント
• Model Context Protocol
• FastMCP
• OpenAI エージェント
• 学術研究の例