STARWARCLOUD STARWAR.AI
返回市场
亚历克斯-MCP

亚历克斯-MCP

作者：drAbreu21 星标更新：2025-08-12
安装使用来源：spider==github.com

项目介绍

<div align="center"> <img src="img/oam_logo_rectangular.png" alt="OpenAlex MCP Server" width="600"/>

OpenAlex 作者消歧 MCP 服务器

MCP Python OpenAlex License Optimized

</div>

一个用于作者消歧和学术研究的简化型模型上下文协议（MCP）服务器，使用OpenAlex.org API。特别设计用于具有优化数据结构和增强功能的AI代理。

🎯 关键特性

🔍 核心能力

  • 高级作者消歧：处理复杂的事业转变和姓名变化
  • 机构解析：当前和过去的隶属关系及转换追踪
  • 学术作品检索：期刊文章、信件和研究报告
  • 引文分析：H指数、引文数量和影响力指标
  • ORCID集成：通过ORCID标识符实现最高精度匹配

🚀 AI代理优化

  • 简化数据：专注于消歧所需的关键信息
  • 快速处理：优化的数据结构以实现快速分析
  • 智能过滤：增强的过滤选项以支持针对性查询
  • 干净输出：结构化响应以优化AI推理

🤖 代理集成

  • 多个候选者：排名结果以供自动决策
  • 结构化响应：干净、可解析的输出以优化LLMs
  • 错误处理：带有信息性消息的优雅降级
  • 增强过滤：仅限期刊、引文阈值和时间过滤

🏛️ 专业级别

  • 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  # 在Windows上：venv\Scripts\activate

  3. 安装包：

    pip install -e .

  4. 配置环境：

    export OPENALEX_MAILTO=your-email@domain.com

  5. 运行服务器：

    ./run_alex_mcp.sh
# 或，如果作为CLI工具安装：
alex-mcp

⚙️ MCP配置

Claude Desktop配置

添加到您的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代理集成

您可以在OpenAI代理工作流中使用此MCP服务器，通过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=1
) as alex_mcp:
    await alex_mcp.connect()
    tools = await alex_mcp.list_tools()
    print(f"可用工具: {[tool.name for tool in tools]}")

学术研究代理集成

此MCP服务器专门针对学术研究工作流程进行了优化：

# 针对学术研究工作流程优化
from alex_agent import run_author_research

# 带有简化数据的增强功能
result = await run_author_research(
    "查找在EMBO发表近期论文的J. Abreu"
)

# 清晰、结构化的输出以供AI处理
print(f"成功: {result['workflow_metadata']['success']}")
print(f"质量: {result['research_result']['metadata']['result_analysis']['quality_score']}/100")

直接启动uvx

# 标准启动
uvx --from git+https://github.com/drAbreu/alex-mcp.git@4.1.0 alex-mcp

# 带有环境变量
OPENALEX_MAILTO=your-email@domain.com uvx --from git+https://github.com/drAbreu/alex-mcp.git@4.1.0 alex-mcp

🛠️ 可用工具

1. autocomplete_authors ⭐ 新增

使用OpenAlex自动完成功能获取多个作者候选人以进行智能消歧。

参数：

  • 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"
    }
  ]
}

使用模式：

# 获取多个候选人以进行消歧
candidates = await autocomplete_authors(
    "James Briscoe", 
    context="Francis Crick Institute发育生物学"
)

# AI根据机构上下文选择最佳匹配
# 比单一搜索结果准确得多！

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": "欧洲分子生物学组织",
            "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": "天体物理学",
          "score": 0.8
        },
        {
          "display_name": "机器学习",
          "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": "大型语言模型在生物医学应用中的平台",
      "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": "欧洲分子生物学组织"
            }
          ]
        }
      ],
      "locations": [
        {
          "source": {
            "display_name": "自然生物技术",
            "type": "journal"
          }
        }
      ],
      "open_access": {
        "is_oa": true
      },
      "primary_topic": {
        "display_name": "生物医学工程"
      }
    }
  ]
}

特点：全面的作品数据，灵活的过滤以支持有针对性的查询

📊 数据优化

聚焦信息架构

此MCP服务器提供了聚焦且结构化的数据，特别设计用于AI代理消费：

作者数据特点

  • 身份解析：姓名、ORCID、替代名称以供消歧
  • 隶属关系跟踪：当前和历史机构连接
  • 影响指标：引文数量、H指数和学术影响力
  • 研究背景：领域、概念和专业知识
  • 职业生涯分析：时间隶属关系变化和过渡

作品数据特点

  • 出版元数据：标题、DOI、出版物和出版细节
  • 影响评估：引文数量和学术影响力
  • 访问信息：开放访问状态和可用性
  • 作者详情：完整的作者名单和机构隶属关系
  • 研究分类：主题、概念和领域分类

增强过滤

# 目标高影响力的期刊文章
works = await retrieve_author_works(
    author_id="https://openalex.org/A123456789",
    type="journal-article",      # 专注于期刊出版物
    open_access_is_oa=True,      # 仅开放访问
    order_by="citations",        # 引文最多优先
    limit=15
)

# 职业过渡分析
authors = await search_authors(
    name="J. Abreu",
    institution="EMBO",          # 当前机构
    topic="机器学习",            # 研究重点
    limit=10
)

🧪 示例用法

作者消歧

from alex_mcp.server import search_authors_core

# 综合作者搜索
results = search_authors_core(
    name="J Abreu Vicente",
    institution="EMBO",
    topic="机器学习",
    limit=20
)

print(f"找到 {results.total_count} 名候选人")
for author in results.results:
    print(f"- {author.display_name}")
    if author.affiliations:
        current_inst = author.affiliations[0].institution.display_name
        print(f"  机构: {current_inst}")
    print(f"  指标: {author.cited_by_count} 引文，H指数 {author.summary_stats.h_index}")
    if author.x_concepts:
        fields = [c.display_name for c in author.x_concepts[:3]]
        print(f"  研究: {', '.join(fields)}")

学术作品分析

from alex_mcp.server import retrieve_author_works_core

# 综合作品检索
works = retrieve_author_works_core(
    author_id="https://openalex.org/A5058921480",
    type="journal-article",      # 学术焦点
    order_by="citations",        # 影响力排序
    limit=20
)

print(f"找到 {works.total_count} 篇出版物")
for work in works.results:
    print(f"- {work.title}")
    if work.locations:
        journal = work.locations[0].source.display_name
        print(f"  发表于: {journal} ({work.publication_year})")
    print(f"  影响力: {work.cited_by_count} 引文")
    if work.open_access and work.open_access.is_oa:
        print("  ✓ 开放访问")

机构和领域分析

# 分析职业路径
def analyze_career_path(author_result):
    affiliations = author_result.affiliations
    if len(affiliations) > 1:
        print("职业路径：")
        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}")
    
    # 研究演变
    if author_result.x_concepts:
        print("研究领域：")
        for concept in author_result.x_concepts[:5]:
            print(f"  {concept.display_name} (得分: {concept.score:.2f})")

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

🔧 配置选项

环境变量

# 必需
export OPENALEX_MAILTO=your-email@domain.com

# 可选设置
export OPENALEX_MAX_AUTHORS=100             # 每次查询的最大作者数
export OPENALEX_USER_AGENT=research-agent-v1.0
export ALEX_MCP_VERSION=4.1.0

# 速率限制（尊重使用）
export OPENALEX_RATE_PER_SEC=10
export OPENALEX_RATE_PER_DAY=100000

性能调整

# 适用于综合研究应用
config = {
    "max_authors_per_query": 25,     # 详细的作者分析
    "max_works_per_author": 50,      # 完整的出版历史
    "enable_all_filters": True,      # 完整的过滤能力
    "detailed_affiliations": True,   # 完整的机构数据
    "research_concepts": True        # 详细的概念分析
}

🧑‍💻 开发与测试

项目结构

alex-mcp/
├── src/alex_mcp/
│   ├── server.py              # 主MCP服务器
│   ├── data_objects.py        # 数据模型和结构
│   └── utils.py               # 工具函数
├── examples/
│   ├── basic_usage.py         # 简单示例
│   ├── advanced_queries.py    # 复杂查询示例
│   └── integration_demo.py    # AI代理集成
├── tests/
│   ├── test_server.py         # 服务器功能测试
│   └── test_integration.py    # 集成测试
└── docs/
    └── api_reference.md       # 详细的API文档

运行测试

# 安装测试依赖
pip install -e ".[test]"

# 运行功能测试
pytest tests/test_server.py -v

# 使用真实查询测试
python examples/basic_usage.py

# 测试AI代理集成
python examples/integration_demo.py

开发示例

# 测试作者消歧