使用说明

INDRA CoGEx MCP服务器

模型上下文协议服务器提供对INDRA CoGEx生物医学知识图谱-28+数据库的统一访问，110个API端点，可通过16个组合双向工具访问。

概述

它做什么：将人工智能代理与涵盖基因、疾病、药物、途径、变体和临床试验的全面生物医学知识联系起来。

为什么这很重要：与其单独查询28个以上的数据库，不如使用一个具有智能实体解析、自动回退和基于证据的结果的MCP服务器。

运作原理：双后端（Neo4j+REST），双向查询（gene→组织和组织→基因）、自动缓存、生产级可靠性。

安装

快速启动（地方发展）

# Clone repository
git clone https://github.com/ejmockler/indra-cogex-mcp.git
cd indra-cogex-mcp

# Install in development mode
pip install -e ".[dev]"

# Configure credentials
cp .env.example .env
# Edit .env with your Neo4j credentials (see Security section)

# Start server
cogex-mcp

全系统安装（pipx）

要与本地LLM工具（Ollama等）一起使用，请使用pipx进行全局安装：

# Install pipx if needed
brew install pipx  # macOS
# or: python3 -m pip install --user pipx

# Install cogex-mcp
pipx install git+https://github.com/ejmockler/indra-cogex-mcp.git

# Configure credentials
# .env file goes in: ~/.local/pipx/venvs/cogex-mcp/lib/python3.X/.env
cp .env.example ~/.local/pipx/venvs/cogex-mcp/lib/python3.14/.env
# Edit the file with your Neo4j credentials

# Verify installation
cogex-mcp --help

备注：替换 python3.14 使用您的Python版本。通过以下方式查找： ls ~/.local/pipx/venvs/cogex-mcp/lib/

MCP客户端集成

备注：REST API回退仅支持基本基因表达式查询。要完全访问所有16个工具（途径、药物、疾病、富集、临床试验、变体等），请配置Neo4j凭据。

克劳德桌面版

添加到 ~/Library/Application Support/Claude/claude_desktop_config.json （macOS）或 %APPDATA%\Claude\claude_desktop_config.json （Windows）：

选项A:Neo4j直接访问（推荐-全工具覆盖）

{
  "mcpServers": {
    "indra-cogex": {
      "command": "cogex-mcp",
      "env": {
        "NEO4J_URL": "bolt://your-server:7687",
        "NEO4J_USER": "neo4j",
        "NEO4J_PASSWORD": "your_password"
      }
    }
  }
}

选项B:REST API回退（仅演示-仅基因查询）

{
  "mcpServers": {
    "indra-cogex": {
      "command": "cogex-mcp",
      "env": {
        "USE_REST_FALLBACK": "true",
        "REST_API_BASE": "https://discovery.indra.bio"
      }
    }
  }
}

⚠️ 仅限于基因↔组织与基因↔GO术语查询。大多数工具不可用。

配置后重新启动Claude Desktop。

Cline（VSCode扩展）

Cline具有内置的MCP支持。添加到VSCode设置或Cline配置：

推荐：Neo4j直接访问

{
  "cline.mcpServers": {
    "indra-cogex": {
      "command": "cogex-mcp",
      "env": {
        "NEO4J_URL": "bolt://your-server:7687",
        "NEO4J_USER": "neo4j",
        "NEO4J_PASSWORD": "your_password"
      }
    }
  }
}

对于REST回退（较慢），请设置 USE_REST_FALLBACK=true 和 REST_API_BASE=https://discovery.indra.bio 相反。

用例：科学文献综述、药物发现工作流程、在开发过程中分析基因表达数据集。

Zed编辑

添加到Zed的MCP设置(~/.config/zed/settings.json):

{
  "context_servers": {
    "indra-cogex": {
      "command": "cogex-mcp",
      "env": {
        "NEO4J_URL": "bolt://your-server:7687",
        "NEO4J_USER": "neo4j",
        "NEO4J_PASSWORD": "your_password"
      }
    }
  }
}

对于REST回退，设置 USE_REST_FALLBACK=true 和 REST_API_BASE 而不是Neo4j凭据。

用例：编辑研究代码、内联路径/疾病查询时的实时生物医学上下文。

光标

Cursor通过其配置支持MCP。添加到光标设置：

{
  "mcp": {
    "servers": {
      "indra-cogex": {
        "command": "cogex-mcp",
        "env": {
          "NEO4J_URL": "bolt://your-server:7687",
          "NEO4J_USER": "neo4j",
          "NEO4J_PASSWORD": "your_password"
        }
      }
    }
  }
}

对于REST回退，请使用 USE_REST_FALLBACK=true 和 REST_API_BASE 相反。

用例：人工智能辅助生物信息学开发，代码注释中的自动基因注释。

Continue.dev

添加以继续配置(~/.continue/config.json):

{
  "mcpServers": [
    {
      "name": "indra-cogex",
      "command": "cogex-mcp",
      "env": {
        "NEO4J_URL": "bolt://your-server:7687",
        "NEO4J_USER": "neo4j",
        "NEO4J_PASSWORD": "your_password"
      }
    }
  ]
}

对于REST回退，请使用 USE_REST_FALLBACK=true 和 REST_API_BASE 相反。

用例：使用生物医学上下文生成内联文档，研究代码自动完成。

本地LLM（Ollama+Python）

通过Python与任何本地LLM一起使用：

from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

# Connect to MCP server with Neo4j (recommended)
server_params = StdioServerParameters(
    command="cogex-mcp",
    env={
        "NEO4J_URL": "bolt://your-server:7687",
        "NEO4J_USER": "neo4j",
        "NEO4J_PASSWORD": "your_password"
    }
)

# OR use REST fallback (slower, no credentials needed)
# server_params = StdioServerParameters(
#     command="cogex-mcp",
#     env={
#         "USE_REST_FALLBACK": "true",
#         "REST_API_BASE": "https://discovery.indra.bio"
#     }
# )

async with stdio_client(server_params) as (read, write):
    async with ClientSession(read, write) as session:
        # Initialize
        await session.initialize()

        # List available tools
        tools = await session.list_tools()

        # Call tool
        result = await session.call_tool(
            "cogex_query_gene_or_feature",
            arguments={
                "mode": "gene_to_features",
                "gene": "TP53",
                "response_format": "json"
            }
        )

用例：定制研究管道、自动化假设生成、本地优先生物医学分析。

为什么将此MCP用于生物医学研究

最强大的:

药物发现人工智能试剂：在一次通话中查询28个以上数据库中的药物靶向疾病关系
科学写作助理：循证引用、自动文献综合
生物信息学工作流程：基因集富集、通路分析、变体解释集成到代码编辑器中
研究自动化：系统评价、假设生成、数据集注释
本地法学硕士研究：隐私保护生物医学查询、离线分析、定制研究工具

主要优势双向查询意味着您可以从任何实体（基因、疾病、药物、表型）开始，在一个统一的界面中双向遍历知识图——正向和反向查找。

可用工具

核心发现

工具	功能	双向
`cogex_query_gene_or_feature`	基因↔ 组织、GO术语、结构域、表型	✓
`cogex_extract_subnetwork`	图遍历、机械关系、共享调节器	✓
`cogex_enrichment_analysis`	GSEA，通路过度代表性分析	✓
`cogex_query_drug_or_effect`	药物↔ 副作用、靶点、适应症	✓
`cogex_query_disease_or_phenotype`	疾病↔ 表型、相关基因	✓

专业查询

工具	功能
`cogex_query_pathway`	路径成员资格和共享路径发现
`cogex_query_cell_line`	CCLE/DepMap细胞系特性
`cogex_query_clinical_trials`	ClinicalTrials.gov按疾病/药物/基因搜索
`cogex_query_literature`	PubMed/INDRA证据检索
`cogex_query_variants`	GWAS目录和DisGeNet变体关联

公用事业

工具	功能
`cogex_resolve_identifiers`	身份证系统之间的转换（HGNC、Entrez、Ensembl等）
`cogex_check_relationship`	实体关系的布尔验证
`cogex_get_ontology_hierarchy`	导航GO/疾病/表型本体论
`cogex_query_cell_markers`	细胞类型标记基因发现
`cogex_analyze_kinase_enrichment`	磷酸蛋白质组学激酶底物分析
`cogex_query_protein_functions`	酶活性和分子功能注释

覆盖：100/110 API端点（91%）•所有关系工具都支持正向+反向查询

示例用法

# Comprehensive gene profile
cogex_query_gene_or_feature(mode="gene_to_features", gene="TP53", include_all=True)

# Tissue expression query (reverse direction)
cogex_query_gene_or_feature(mode="tissue_to_genes", tissue="brain")

# Drug side effect discovery
cogex_query_drug_or_effect(mode="side_effect_to_drugs", side_effect="nausea")

# Gene set enrichment
cogex_enrichment_analysis(
    analysis_type="continuous",
    ranked_genes={"BRCA1": 3.2, "TP53": 2.8, ...},
    source="reactome"
)

# Network analysis - find shared regulators
cogex_extract_subnetwork(mode="shared_upstream", genes=["IL6", "IL1B", "TNF"])

# Phosphoproteomics analysis
cogex_analyze_kinase_enrichment(phosphosites=["MAPK1_T185", "MAPK1_Y187"])

子网提取

从INDRA-CoGEx知识图中提取机械网络：

快速开始

from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

server_params = StdioServerParameters(
    command="cogex-mcp",
    env={
        "NEO4J_URL": "bolt://your-server:7687",
        "NEO4J_USER": "neo4j",
        "NEO4J_PASSWORD": "your_password"
    }
)

async with stdio_client(server_params) as (read, write):
    async with ClientSession(read, write) as session:
        await session.initialize()

        # Direct interactions between TP53 and MDM2
        result = await session.call_tool(
            "cogex_extract_subnetwork",
            arguments={
                "mode": "direct",
                "genes": ["TP53", "MDM2"],
                "min_evidence_count": 2,
                "response_format": "json"
            }
        )

查询模式

模式	模式	用例	示例
直接	A→B	了解基因如何直接相互作用	TP53-MDM2反馈回路
调解的	A→X→B	发现连接基因的途径	ALS基因连接
共享_上游	A←X→B	查找主调节因子	凋亡调节因子
共享_下游	A→X←B	寻找共同靶点	转录因子靶点
源目标	S→[T1、T2、T3]	映射下游信号	MAPK1底物

高级过滤

# Brain-specific Alzheimer's network
result = await session.call_tool(
    "cogex_extract_subnetwork",
    arguments={
        "mode": "direct",
        "genes": ["APP", "PSEN1", "MAPT"],
        "tissue_filter": "brain",
        "min_evidence_count": 3,
        "min_belief_score": 0.7,
        "statement_types": ["Phosphorylation", "Activation"],
        "response_format": "json"
    }
)

# MAPK phosphorylation cascade
result = await session.call_tool(
    "cogex_extract_subnetwork",
    arguments={
        "mode": "source_to_targets",
        "source_gene": "MAPK1",
        "target_genes": ["FOS", "JUN", "ELK1", "MYC"],
        "statement_types": ["Phosphorylation"],
        "include_evidence": True,
        "max_statements": 100,
        "response_format": "json"
    }
)

输出格式

JSON响应结构：

{
  "nodes": [
    {
      "name": "TP53",
      "curie": "hgnc:11998",
      "namespace": "hgnc",
      "identifier": "11998"
    }
  ],
  "statements": [
    {
      "stmt_hash": "abc123...",
      "stmt_type": "Phosphorylation",
      "subject": {"name": "ATM", "curie": "hgnc:795"},
      "object": {"name": "TP53", "curie": "hgnc:11998"},
      "residue": "S",
      "position": "15",
      "evidence_count": 12,
      "belief_score": 0.95,
      "sources": ["reach", "sparser"]
    }
  ],
  "statistics": {
    "node_count": 10,
    "edge_count": 25,
    "statement_types": {
      "Phosphorylation": 15,
      "Activation": 10
    },
    "avg_evidence_per_statement": 8.2,
    "avg_belief_score": 0.87
  }
}

文档

综合指南: docs/subnetwork_extraction_guide.md
代码示例: 示例/子网络提取.py
集成测试: 测试/集成/test_tool02_subnetwork_integration.py

建筑

数据源

28+集成数据库：BGee、GO、Reactome、WikiPathways、ChEMBL、SIDER、DisGeNet、CCLE、DepMap、ClinicalTrials.gov、PubMed、CellMarker、GWAS目录等。

连接策略

主要的，重要的：通过直接访问Neo4j indra_cogex.client （<500ms简单查询）
- 全面覆盖：所有16个工具，100/110个端点
- 高级查询：子网、富集分析、文献证据
后备方案：discovery.indra.bio上的REST API（公共访问，无凭据）
- 覆盖范围有限：16种工具中的1种（仅限基因表达和GO术语）
- 简单查询：基因↔组织，基因↔GO术语查找
- 仅用于：快速演示、测试或Neo4j不可用时
自动：优雅的降级、断路器、智能缓存

⚠️ 生产建议：使用Neo4j凭据。REST回退提供<10%的工具覆盖率，无法执行通路分析、富集、子网络、药物查询、临床试验、变体或文献搜索。

设计理念

组合性：16个工具，而不是110个终点——按生物学问题组织
双向：所有关系工具都支持正向+反向查询
证据确凿：每个结果都可以追溯到源出版物
LLM优化：语义清晰，可操作的错误，字符受限的响应
生产准备就绪：异步、类型安全、缓存、监视

安全

凭证配置

创建 .env 从模板：

cp .env.example .env

选项A：Neo4j+REST回退（建议用于生产环境）

NEO4J_URL=bolt://your-server:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=your_password
USE_REST_FALLBACK=true  # Emergency fallback only

如果Neo4j不可用，则提供完整的16工具覆盖和自动故障转移。

选项B：仅限REST（演示/测试-功能有限）

USE_REST_FALLBACK=true
REST_API_BASE=https://discovery.indra.bio

⚠️ 仅支持16个工具中的1个（基本基因表达查询）。大多数工具都会返回错误。

服务器在启动时验证凭据，并提供可操作的错误消息。凭据从未在日志或错误中公开。

发展

需求

Python 3.10+（推荐3.12）
依赖关系： mcp==1.22.0, pydantic==2.12.4, neo4j==6.0.3, httpx==0.28.1

开发设置

git clone https://github.com/ejmockler/indra-cogex-mcp.git
cd indra-cogex-mcp
pip install -e ".[dev]"

# Run tests
pytest tests/unit -v
pytest tests/integration -v  # Requires Neo4j credentials

# Run linting
ruff check src tests
ruff format src tests
mypy src

CI/CD

多Python测试（3.10、3.11、3.12）
80%覆盖率目标（Codecov）
安全扫描（Bandit+安全）
自动分发构建

文档

实施_ GIDE.md -完整的技术规范、架构
快速启动.md -所有16种工具的详细使用指南
INDRA CoGEx文件 -上游知识图谱来源
api参考 -REST API文档

演出

简单查询：<500ms
复杂分析：<5s
内存基线：<200MB
正常运行时间：99%+

引用

如果您使用INDRA CoGEx，请引用：

Gyori BM等人（2023）。INDRA CoGEx：一个自动组装的生物医学知识图，将因果机制与非因果上下文关系相结合。 bioRxiv.

许可证

此MCP服务器：MIT许可证

INDRA CoGEx：BSD-2条款许可证（东北大学Gyori实验室）

版本: 2.0.0 • 状态：生产就绪• 覆盖：91%（100/110个终点）