OpenAlex Author Disambiguation MCP Server

OpenAlex作者去歧义MCP服务器

    

A. 流线型的 模型上下文协议（MCP）服务器，用于使用OpenAlex.org API进行作者歧义消除和学术研究。专为具有优化数据结构和增强功能的AI代理而设计。

______________________________________________________________________

🎯 主要特点

🔍 核心能力

• 高级作者消除歧义：处理复杂的职业转换和姓名变化
• 机构决议：当前和过去与过渡跟踪的关系
• 学术作品检索：期刊文章、信件和研究论文
• 引文分析：H指数、引用计数和影响指标
• ORCID集成：与ORCID标识符匹配的精度最高

🚀 AI代理优化

• 简化数据：专注于消除歧义的基本信息
• 快速处理：优化数据结构，实现快速分析
• 智能过滤：针对目标查询的增强过滤选项
• 清洁输出：针对AI推理优化的结构化响应

🤖 代理集成

• 多名候选人：对自动化决策结果进行排名
• 结构化响应：针对LLM优化的干净、可解析的输出
• 错误处理：优雅的降级，信息丰富
• 增强过滤：仅限期刊、引用阈值和时间过滤器

🏛️ 职业等

• MCP最佳实践：按照官方指南使用FastMCP构建
• 工具注释：正确的MCP工具注释，以实现最佳的客户端集成
• 资源管理：高效的HTTP客户端管理和清理
• 速率限制：尊重API使用，适当延迟

______________________________________________________________________

🚀 快速开始

先决条件

• Python 3.10或更高版本
• MCP兼容客户端（例如Claude Desktop）
• 电子邮件地址（由OpenAlex API提供）

安装

有关详细的安装说明，请参阅 安装.md.

1. 克隆存储库：

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

1. 创建虚拟环境：

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

1. 安装软件包：

   pip install -e .

1. 配置环境：

   export OPENALEX_MAILTO=your-email@domain.com

1. 运行服务器：

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

______________________________________________________________________

⚙️ MCP配置

Claude桌面配置

添加到您的Claude Desktop配置文件中：

{
  "mcpServers": {
    "alex-mcp": {
      "command": "/path/to/alex-mcp/run_alex_mcp.sh",
      "env": {
        "OPENALEX_MAILTO": "your-email@domain.com"
      }
    }
  }
}

替换 /path/to/alex-mcp 使用系统上存储库的实际路径。

______________________________________________________________________

🤖 与AI代理一起使用

OpenAI代理集成

您可以使用以下命令将此MCP服务器加载到OpenAI代理工作流中 agents.mcp.MCPServerStdio 接口：

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/alex-mcp.git@4.1.0",
            "alex-mcp"
        ],
        "env": {
            "OPENALEX_MAILTO": "your-email@domain.com"
        }
    },
    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/alex-mcp.git@4.1.0 alex-mcp

# With environment variables
OPENALEX_MAILTO=your-email@domain.com uvx --from git+https://github.com/drAbreu/alex-mcp.git@4.1.0 alex-mcp

______________________________________________________________________

🛠️ 可用工具

1. 自动补全_作者 ⭐ 新

使用OpenAlex自动完成API智能消除歧义，获得多个作者候选人。

参数：

• name （必填）：要搜索的作者姓名（例如，“James Briscoe”、“M.Ralser”）
• context （可选）：消歧上下文（例如，“弗朗西斯·克里克研究所发育生物学”）
• limit （可选）：最大候选人数（1-10，默认值：5）

主要特点：

• ⚡ 快速：~200ms响应时间
• 🎯 聪明的：多名候选人带有机构提示
• 🧠 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. 搜索_作者

使用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. 检索_作者_作品

使用增强的过滤功能检索给定作者的作品。

参数：

• author_id （必填）：OpenAlex作者ID
• limit （可选）：最大结果（1-50，默认值：20）
• order_by （可选）：“日期”或“引用”（默认值：“date”）
• publication_year （可选）：按特定年份筛选
• type （可选）：工作类型过滤器（例如，“期刊文章”）
• 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指数和学术影响力
• 研究背景：领域、概念和领域专业知识
• 职业分析：时间隶属关系变化和过渡

工作数据特征

• 发布元数据：标题、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 OPENALEX_MAILTO=your-email@domain.com

# 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"

______________________________________________________________________

📈 集成示例

学术研究工作流程

与人工智能驱动的研究分析完美集成：

# 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许可证获得许可。看 许可证 了解详情。

______________________________________________________________________

🌐 链接

• OpenAlex API文档
• 模型上下文协议
• FastMCP
• OpenAI代理
• 学术研究实例