Opengenes MCP

🚀 opengenes - mcp

opengenes - mcp是一個基於Model Context Protocol（MCP）的服務器，用於訪問OpenGenes數據庫。它為AI助手和代理提供了標準化接口，可通過結構化接口查詢全面的生物醫學數據集，助力衰老和長壽研究。

🚀 快速開始

安裝uv

# 下載並安裝uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# 驗證安裝
uv --version
uvx --version

uvx是一個非常實用的工具，它可以在需要時運行Python包。

使用uvx運行

你可以直接使用uvx運行opengenes - mcp服務器，而無需克隆倉庫：

# 以流式HTTP模式運行服務器（默認）
uvx opengenes - mcp

# 或者顯式指定stdio模式
uvx opengenes - mcp stdio

# 在默認（3001）端口以可流式HTTP模式運行服務器
uvx opengenes - mcp server

# 在特定端口運行
uvx opengenes - mcp server --port 8000

# 以SSE模式運行服務器
uvx opengenes - mcp sse

若uvx出現問題，通常可通過清理uv緩存解決：

uv cache clean

HTTP模式將啟動一個Web服務器，你可以在http://localhost:3001/mcp訪問（文檔位於http://localhost:3001/docs）。STDIO模式專為通過標準輸入輸出通信的MCP客戶端設計，而SSE模式使用服務器發送事件進行實時通信。

注意：目前我們沒有Swagger/OpenAPI接口，因此直接在瀏覽器中訪問服務器不會顯示太多有用信息。若要探索可用工具和功能，你應使用MCP Inspector（見下文）或通過MCP客戶端連接以查看可用工具。

配置AI客戶端（Anthropic Claude Desktop、Cursor、Windsurf等）

我們為不同用例提供了預配置的JSON文件：

• STDIO模式（推薦）：使用mcp - config - stdio.json
• HTTP模式：使用mcp - config.json
• 本地開發：使用mcp - config - stdio - debug.json

配置視頻教程

若要獲取如何使用AI客戶端配置MCP服務器的可視化指南，請查看我們的配置教程視頻，該視頻針對我們的姊妹MCP服務器（biothings - mcp）。OpenGenes MCP服務器的配置原則完全相同，只需使用上述提供的相應JSON配置文件。

檢查OpenGenes MCP服務器

npx @modelcontextprotocol/inspector --config mcp - config - stdio.json --server opengenes - mcp

npx @modelcontextprotocol/inspector --config mcp - config.json --server opengenes - mcp

npx @modelcontextprotocol/inspector --config mcp - config - stdio - debug.json --server opengenes - mcp

npx @modelcontextprotocol/inspector

與AI系統集成

只需將你的AI客戶端（如Cursor、Windsurf、ClaudeDesktop、帶有Copilot的VS Code或[其他客戶端](https://github.com/punkpeye/awesome - mcp - clients)）指向使用倉庫中適當的配置文件。

倉庫設置

# 克隆倉庫
git clone https://github.com/longevity - genie/opengenes - mcp.git
cd opengenes - mcp
uv sync

運行MCP服務器

如果你已經克隆了倉庫，可以使用uv運行服務器：

# 在本地啟動MCP服務器（HTTP模式）
uv run server

# 或者以STDIO模式啟動
uv run stdio

# 或者以SSE模式啟動
uv run sse

✨ 主要特性

• 標準化接口：實現了Model Context Protocol（MCP），為訪問衰老和長壽研究數據提供標準化接口。
• 自動數據更新：自動從[Hugging Face Hub](https://huggingface.co/longevity - genie/bio - mcp - data)的opengenes文件夾下載最新的OpenGenes數據庫和文檔，無需手動管理文件。
• 多模式支持：支持多種運行模式，如STDIO、HTTP、SSE，滿足不同場景需求。
• 安全可靠：提供只讀訪問、輸入驗證和錯誤處理等安全特性，確保數據安全。

📦 安裝指南

如快速開始部分所述，需先安裝uv：

curl -LsSf https://astral.sh/uv/install.sh | sh

然後可使用uvx運行opengenes - mcp服務器。

💻 使用示例

基礎用法

以下是OpenGenes MCP服務器與AI助手實際協作的示例：


此示例展示瞭如何通過AI助手使用自然語言查詢OpenGenes數據庫，該查詢通過MCP服務器轉換為SQL查詢。你可以在聊天界面中使用此數據庫進行研究問題查詢，也可在基於AI的開發工具（如Cursor、Windsurf、帶有Copilot的VS Code）中使用，在編碼時直接訪問衰老和長壽研究數據，顯著提高生物信息學工作效率。

高級用法

如果你想更深入瞭解Model Context Protocol是什麼以及如何更高效地使用它，你可以參加[DeepLearning AI課程](https://www.deeplearning.ai/short - courses/mcp - build - rich - context - ai - apps - with - anthropic/)或在YouTube上搜索MCP相關視頻。

📚 詳細文檔

數據源和更新

OpenGenes MCP服務器自動從Hugging Face Hub上的[longevity - genie/bio - mcp - data](https://huggingface.co/longevity - genie/bio - mcp - data)倉庫下載數據，確保：

• 始終保持最新：自動訪問最新的OpenGenes數據庫，無需手動更新。
• 可靠分發：集中式數據託管，支持版本控制和變更跟蹤。
• 高效緩存：下載的文件會在本地緩存，以減少網絡請求。
• 離線支持：支持本地備用文件，用於開發和離線使用。

數據文件存儲在Hugging Face倉庫的opengenes子文件夾中，包括：

• open_genes.sqlite - 完整的OpenGenes數據庫
• prompt.txt - 數據庫模式文檔和使用指南

可用工具

該服務器提供了三個主要工具，用於與OpenGenes數據庫進行交互：

1. opengenes_db_query(sql: str) - 對OpenGenes數據庫執行只讀SQL查詢
2. opengenes_get_schema_info() - 獲取詳細的模式信息，包括表、列和枚舉
3. opengenes_example_queries() - 獲取帶有描述的示例SQL查詢列表

可用資源

1. resource://db - prompt - 完整的數據庫模式文檔和使用指南
2. resource://schema - summary - 表格及其用途的格式化摘要

數據庫模式

示例查詢

-- 獲取進行最多壽命實驗的前10個基因
SELECT HGNC, COUNT(*) as experiment_count 
FROM lifespan_change 
WHERE HGNC IS NOT NULL 
GROUP BY HGNC 
ORDER BY experiment_count DESC 
LIMIT 10;

-- 查找在小鼠中延長壽命的基因
SELECT DISTINCT HGNC, effect_on_lifespan 
FROM lifespan_change 
WHERE model_organism = 'mouse' 
AND effect_on_lifespan = 'increases lifespan' 
AND HGNC IS NOT NULL;

-- 獲取與基因相關的衰老標誌
SELECT HGNC, "hallmarks of aging" 
FROM gene_hallmarks 
WHERE "hallmarks of aging" LIKE '%mitochondrial%';

-- 按種族查找與長壽相關的基因
SELECT HGNC, "polymorphism type", "nucleotide substitution", ethnicity 
FROM longevity_associations 
WHERE ethnicity LIKE '%Italian%';

-- 查找同時具有壽命影響和長壽關聯的基因
SELECT DISTINCT lc.HGNC 
FROM lifespan_change lc 
INNER JOIN longevity_associations la ON lc.HGNC = la.HGNC 
WHERE lc.HGNC IS NOT NULL;

安全特性

• 只讀訪問：僅允許SELECT查詢
• 輸入驗證：阻止INSERT、UPDATE、DELETE、DROP、CREATE、ALTER、TRUNCATE操作
• 錯誤處理：提供全面的錯誤處理和信息豐富的錯誤消息

測試與驗證

MCP服務器提供了全面的測試，包括使用LLM作為評判的測試，用於評估對複雜查詢的響應質量。但為節省成本，基於LLM的測試在CI中默認禁用。

環境設置

如果你想運行使用Gemini模型的MCP函數的LLM代理測試，需要在項目根目錄創建一個.env文件，並設置你的Gemini API密鑰：

echo "GEMINI_API_KEY=your - gemini - api - key - here" > .env

注意：.env文件和Gemini API密鑰僅在運行LLM代理測試時需要。所有其他測試和基本MCP服務器功能無需任何API密鑰即可工作。

運行測試

運行MCP服務器的測試：

uv run pytest -vvv -s

你也可以運行手動測試：

uv run python test/manual_test_questions.py

你可以像使用uvx一樣，將MCP Inspector與本地構建的MCP服務器一起使用。

可探索的研究問題

🔧 技術細節

MCP是一種協議，它彌合了AI系統與專業領域知識之間的差距，具有以下特點：

• 結構化訪問：直接連接到權威的衰老和長壽研究數據
• 自然語言查詢：通過SQL簡化與專業數據庫的交互
• 類型安全：通過FastMCP實現強類型和驗證
• AI集成：與AI助手和代理無縫集成

📄 許可證

本項目採用MIT許可證。

致謝

• [OpenGenes數據庫](https://open - genes.com/)提供了全面的衰老研究數據
  • Rafikova E, Nemirovich - Danchenko N, Ogmen A, Parfenenkova A, Velikanova A, Tikhonov S, Peshkin L, Rafikov K, Spiridonova O, Belova Y, Glinin T, Egorova A, Batin M. Open Genes - a new comprehensive database of human genes associated with aging and longevity. Nucleic Acids Res. 2024 Jan 5;52(D1):D950 - D962. doi: 10.1093/nar/gkad712. PMID: 37665017; PMCID: PMC10768108.
• Model Context Protocol提供了協議規範
• FastMCP提供了MCP服務器框架

本項目是[Longevity Genie](https://github.com/longevity - genie)組織的一部分，該組織開發用於健康、遺傳學和長壽研究的開源AI助手和庫。

Longevity Genie的其他MCP服務器

我們還為生物醫學研究開發了其他專業MCP服務器：

• [biothings - mcp](https://github.com/longevity - genie/biothings - mcp) - 用於BioThings.io API的MCP服務器，提供對基因註釋（mygene.info）、變異註釋（myvariant.info）和化合物數據（mychem.info）的訪問

我們得到了以下機構的支持：


HEALES - 健康壽命延長協會

和

[](https://ibima.med.uni - rostock.de/)

[IBIMA - 醫學與衰老研究生物統計學與信息學研究所](https://ibima.med.uni - rostock.de/)

🤝 貢獻

我們歡迎社區的貢獻！無論你是研究人員、開發者還是對衰老和長壽研究感興趣的愛好者，都有多種方式參與其中：

貢獻方式

• 🐛 報告Bug：發現問題？請在GitHub上創建一個詳細的issue。
• 💡 提出功能請求：有新功能的想法？我們很樂意聽取！
• 📝 完善文檔：幫助改進我們的文檔、示例或教程。
• 🧪 參與測試：添加測試用例，特別是針對邊緣情況或新查詢模式的測試。
• 🔍 保障數據質量：幫助識別和報告數據不一致問題或提出改進建議。
• 🚀 優化性能：優化查詢、改進緩存或提升服務器性能。
• 🌐 拓展集成：為新的MCP客戶端或AI系統創建示例。
• 🎥 製作教程和視頻：創建教程、視頻指南或教育內容，展示如何使用MCP服務器。
• 📖 分享用戶故事：分享你使用我們MCP服務器的研究工作流程和成功故事。
• 🤝 促進社區推廣：幫助我們在生物信息學社區推廣MCP的應用。

開始貢獻

1. Fork倉庫
2. 創建一個功能分支 (git checkout -b feature/amazing - feature)
3. 進行更改並添加測試
4. 運行測試套件 (uv run pytest)
5. 提交更改 (git commit -m 'Add amazing feature')
6. 將更改推送到你的分支 (git push origin feature/amazing - feature)
7. 打開一個Pull Request

開發指南

• 遵循現有的代碼風格（我們使用black進行格式化）
• 為新功能添加測試
• 根據需要更新文檔
• 保持提交內容聚焦，並編寫清晰的提交消息

交流討論

如有問題或想法，請隨時創建一個issue進行討論！我們很友好，總是樂意幫助新手入門。你的貢獻有助於推動開放科學和長壽研究的發展。

⚠️ 已知問題

數據庫覆蓋範圍

目前，此MCP服務器僅使用了完整OpenGenes數據庫的一部分。完整的OpenGenes數據庫包含更多的表和數據，尚未包含在我們的MCP實現中。我們需要貢獻者幫助擴展對完整數據庫的支持！ 如果你有興趣幫助擴展數據庫覆蓋範圍，請參閱我們的貢獻部分。

測試覆蓋範圍

雖然我們提供了全面的測試，包括使用LLM作為評判的評估，但並非所有測試用例都已針對實際的OpenGenes Web界面進行了手動驗證。一些自動化測試結果可能需要手動驗證以確保準確性。歡迎貢獻者幫助提高測試覆蓋範圍和驗證質量。