Ncbi Gene MCP Client

🚀 NCBI Gene MCP客户端

🧬 用于从NCBI Entrez API获取基因和蛋白质元数据的MCP客户端

本项目提供了一个模型上下文协议（MCP）客户端，它与NCBI Entrez API对接，以获取有关基因和蛋白质的详细信息。它既可以作为独立的命令行工具使用，也可以作为MCP服务器与支持MCP的客户端集成。

🚀 快速开始

本项目的客户端允许你通过命令行或Python API与NCBI Entrez API交互，获取基因和蛋白质的详细信息。以下是使用客户端的基本步骤：

1. 安装客户端：可以从源代码或PyPI安装。
2. 配置客户端：建议提供你的电子邮件地址和API密钥，以遵守NCBI API的使用规则并提高请求速率限制。
3. 使用客户端：可以通过命令行工具或Python API进行基因搜索、获取基因信息等操作。

✨ 主要特性

• 基因搜索：使用灵活的查询条件搜索基因。
• 基因信息获取：通过NCBI基因ID获取详细的基因元数据。
• 蛋白质信息获取：通过NCBI蛋白质ID获取蛋白质详细信息。
• 符号搜索：按基因符号搜索基因，并可选择过滤生物种类。
• 速率限制：内置对NCBI API速率限制的支持。
• MCP服务器：提供JSON - RPC服务器，用于MCP协议集成。
• CLI接口：易于使用的命令行接口。

📦 安装指南

从源代码安装（开发模式）

# 克隆仓库
git clone <repository-url>
cd ncbi_gene_mcp_client

# 以开发模式安装
pip install -e .

从PyPI安装（如果可用）

pip install ncbi_gene_mcp_client

💻 使用示例

基础用法

命令行接口

安装完成后，你可以使用以下CLI命令：

演示（快速开始）

ncbi-gene-client demo

搜索基因

ncbi-gene-client search-genes "BRCA1"
ncbi-gene-client search-genes "breast cancer" --max-results 10

通过ID获取基因信息

ncbi-gene-client gene-info 672  # BRCA1基因

按基因符号搜索

ncbi-gene-client search-symbol BRCA1 --organism human
ncbi-gene-client search-symbol TP53

获取蛋白质信息

ncbi-gene-client protein-info <protein_id>

使用NCBI凭证（推荐）

ncbi-gene-client --email your@email.com --api-key YOUR_API_KEY demo

Python API

from ncbi_gene_mcp_client.main import NCBIGeneMCPClientBridge

# 初始化客户端
client = NCBIGeneMCPClientBridge(
    email="your@email.com",  # NCBI推荐提供
    api_key="your_api_key"   # 可选，用于提高速率限制
)

# 搜索基因
results = client.search_genes("BRCA1[gene] AND human[organism]")
print(f"找到 {results.count} 个基因")

# 获取详细的基因信息
gene_info = client.fetch_gene_info("672")  # BRCA1
print(f"基因: {gene_info.name}")
print(f"描述: {gene_info.description}")
print(f"生物种类: {gene_info.organism}")

# 按基因符号搜索
genes = client.search_by_gene_symbol("BRCA1", organism="human")
for gene in genes:
    print(f"{gene.name}: {gene.description}")

高级用法

MCP服务器

作为MCP服务器运行，以便与支持MCP的客户端集成：

ncbi-gene-mcp-server

MCP服务器提供以下工具：

• search_genes：使用查询条件搜索基因。
• fetch_gene_info：通过ID获取详细的基因信息。
• fetch_protein_info：通过ID获取蛋白质信息。
• search_by_gene_symbol：按基因符号搜索基因，并可选择过滤生物种类。

📚 详细文档

数据模型

GeneInfo

{
    "gene_id": "672",
    "name": "BRCA1",
    "description": "BRCA1 DNA repair associated",
    "organism": "Homo sapiens",
    "chromosome": "17",
    "map_location": "17q21.31",
    "gene_type": "protein-coding",
    "other_aliases": ["BRCAI", "BRCC1", "BROVCA1"],
    "summary": "This gene encodes a 190 kD nuclear phosphoprotein..."
}

SearchResult

{
    "count": 1,
    "ids": ["672"],
    "query_translation": "BRCA1[gene]"
}

配置

NCBI API使用指南

建议在使用NCBI API时提供你的电子邮件地址：

client = NCBIGeneMCPClientBridge(email="your@email.com")

为了提高速率限制，你还可以提供API密钥：

client = NCBIGeneMCPClientBridge(
    email="your@email.com",
    api_key="your_ncbi_api_key"
)

速率限制

客户端会自动处理NCBI的速率限制要求：

• 无API密钥：每秒3个请求。
• 有API密钥：每秒10个请求。

测试

运行测试套件：

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

# 运行测试
pytest

# 运行带覆盖率的测试
pytest --cov=ncbi_gene_mcp_client

# 运行集成测试（需要网络）
pytest -m integration

开发

开发环境设置

# 克隆并以开发模式安装
git clone <repository-url>
cd ncbi_gene_mcp_client
pip install -e ".[dev]"

# 运行代码检查
flake8 ncbi_gene_mcp_client/
mypy ncbi_gene_mcp_client/

# 格式化代码
black ncbi_gene_mcp_client/

项目结构

ncbi_gene_mcp_client/
├── ncbi_gene_mcp_client/
│   ├── __init__.py
│   ├── main.py          # 主客户端类
│   ├── bridge.py        # NCBI API桥接
│   ├── models.py        # 数据模型
│   ├── mcp_server.py    # MCP服务器实现
│   └── cli.py           # 命令行接口
├── tests/
│   ├── __init__.py
│   └── test_main.py     # 测试套件
├── pyproject.toml       # 项目配置
├── README.md           # 本文件
└── LICENSE             # MIT许可证

NCBI资源

• NCBI Entrez编程实用工具
• NCBI基因数据库
• E-utilities API文档

API方法

核心方法

• method1()：method1的描述。
• method2()：method2的描述。
• method3()：method3的描述。

配置

该包使用配置类进行设置：

from ncbi_gene_mcp_client.main import NCBIGeneMCPClientConfig, NCBIGeneMCPClientBridge

config = NCBIGeneMCPClientConfig(
    base_url="https://api.example.com",
    api_key="your_api_key",
    timeout=30.0
)

bridge = NCBIGeneMCPClientBridge(config)

MCP服务器配置

要将MCP服务器与MCP客户端一起使用，请按以下方式进行配置：

{
  "mcpServers": {
    "ncbi_gene_mcp_client": {
      "command": "ncbi_gene_mcp_client-server",
      "env": {}
    }
  }
}

服务器将自动处理：

• JSON - RPC通信。
• 工具发现和调用。
• 错误处理和报告。

开发

设置开发环境

# 以开发模式安装并包含开发依赖
pip install -e .[dev]

# 运行测试
pytest

# 格式化代码
black ncbi_gene_mcp_client/

# 类型检查
mypy ncbi_gene_mcp_client/

项目结构

ncbi_gene_mcp_client/
├── pyproject.toml      # 包配置
├── README.md          # 本文件
├── LICENSE            # MIT许可证
├── ncbi_gene_mcp_client/         # 主包
│   ├── __init__.py    # 包初始化
│   ├── main.py        # 核心功能
│   └── mcp_server.py  # MCP服务器实现
└── tests/             # 测试文件
    ├── __init__.py
    └── test_main.py   # 核心功能测试

📄 许可证

本项目采用MIT许可证 - 详情请参阅LICENSE文件。

👨‍💻 作者

Mohammad Najeeb
📧 mona00002@uni-saarland.de

🤝 贡献

欢迎贡献代码！请随时提交拉取请求。

支持

如有问题和疑问，请使用GitHub问题跟踪器。