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問題跟蹤器。