使用说明

bio-mcp层间mcp

用于InterProScan蛋白结构域和功能分析的MCP（模型上下文协议）服务器

概述

bio-mcp间mcp服务器通过模型上下文协议提供对InterProScan蛋白质结构域和功能分析功能的访问。它支持同步（快速）和异步（长时间运行）蛋白质序列分析，并为大规模生物信息学工作流程提供全面的作业管理。

特性

蛋白质结构域分析：使用InterProScan进行全面的域名和家族识别
异步作业管理：对具有进度跟踪功能的大型数据集进行后台处理
批处理：同时提交多个蛋白质文件
MCP集成：为AI助手提供完整的模型上下文协议支持
模拟模式：演示功能，无需安装InterProScan
工作坚持性：作业在服务器重启后仍能存活，并具有完全状态恢复功能

目录结构

./
├── README.md               # This file
├── env/                    # Conda environment
├── src/
│   ├── server.py           # MCP server (main entry point)
│   ├── utils.py            # Shared utilities
│   └── jobs/               # Job management system
├── scripts/
│   ├── protein_domain_scan.py      # Basic protein analysis
│   ├── async_job_manager.py        # Async job management
│   ├── mcp_client_demo.py          # MCP client examples
│   └── lib/                        # Shared utilities
├── examples/
│   └── data/               # Demo data
│       ├── sample.fasta            # Small test dataset
│       ├── small_dataset.fasta     # Medium test dataset
│       ├── large_dataset.fasta     # Large test dataset
│       └── config_example.yaml     # Configuration template
├── configs/                # Configuration files
│   ├── default_config.json                # Default settings
│   ├── protein_domain_scan_config.json    # Domain scan config
│   ├── async_job_manager_config.json      # Job manager config
│   └── mcp_client_demo_config.json        # MCP client config
├── jobs/                   # Job storage directory
├── tests/                  # Test suite
└── repo/                   # Original repository

安装

快速设置（推荐）

运行自动安装脚本：

cd interpro_mcp
bash quick_setup.sh

该脚本将创建conda环境，安装所有依赖项，并显示Claude Code配置。看 quick_setup.sh --help 对于以下选项 --skip-env.

先决条件

Conda或Mamba（建议使用曼巴以加快安装速度）
Python 3.10+
InterProScan（可选-模拟模式在没有它的情况下工作）

手动安装（替代）

如果您更喜欢手动安装或需要自定义设置，请按照以下步骤操作 reports/step3_environment.md:

# Navigate to the MCP directory
cd /home/xux/Desktop/ProteinMCP/ProteinMCP/tool-mcps/interpro_mcp

# Create conda environment (use mamba if available)
mamba create -p ./env python=3.10 -y
# or: conda create -p ./env python=3.10 -y

# Activate environment
mamba activate ./env
# or: conda activate ./env

# Install Dependencies
pip install loguru click pandas numpy tqdm
pip install "mcp>=1.1.0" "pydantic>=2.0.0" "pydantic-settings>=2.0.0" "httpx>=0.24.0"
pip install "pytest>=7.0.0" "pytest-asyncio>=0.21.0" "ruff>=0.1.0"

# Install MCP dependencies
pip install fastmcp loguru --force-reinstall --no-cache-dir

本地使用（脚本）

您可以在没有MCP的情况下直接使用脚本进行本地处理。

可用脚本

脚本	描述	示例
`scripts/protein_domain_scan.py`	使用InterProScan进行基本蛋白质结构域分析	见下文
`scripts/async_job_manager.py`	大型数据集的异步作业提交和管理	见下文
`scripts/mcp_client_demo.py`	MCP客户端通信示例	见下文

脚本示例

蛋白质结构域扫描

# Activate environment
mamba activate ./env

# Basic protein analysis
python scripts/protein_domain_scan.py \
  --input examples/data/sample.fasta \
  --output results/domains.tsv \
  --format tsv

# With custom databases
python scripts/protein_domain_scan.py \
  --input examples/data/sample.fasta \
  --output results/pfam_analysis.tsv \
  --databases "Pfam,SMART,Gene3D" \
  --format tsv

# Create sample data for testing
python scripts/protein_domain_scan.py --create-sample

参数：

--input, -i：输入蛋白质FASTA文件（必填）
--output, -o：输出文件路径（默认：结果/目录）
--format：输出格式-tsv、xml、json、gff3（默认：tsv）
--databases：逗号分隔的数据库列表（默认：全部可用）
--config, -c：配置文件路径（可选）
--create-sample：生成测试样本数据

异步作业管理器

# Submit a large analysis job
python scripts/async_job_manager.py \
  --submit \
  --input examples/data/large_dataset.fasta \
  --priority 8 \
  --email user@example.com

# Check job status
python scripts/async_job_manager.py \
  --status <job_id>

# Get job results
python scripts/async_job_manager.py \
  --results <job_id>

# List all jobs
python scripts/async_job_manager.py \
  --list-jobs

# Create large test dataset
python scripts/async_job_manager.py --create-dataset 100

参数：

--submit：提交新的分析作业
--input, -i：输入FASTA文件（提交时需要）
--priority：作业优先级1-10，较高=更紧急（默认值：5）
--email：通知电子邮件（可选）
--status：检查特定作业ID的状态
--results：获取已完成作业的结果
--list-jobs：列出所有提交的作业

MCP客户端演示

# Test basic MCP server communication
python scripts/mcp_client_demo.py \
  --server-type basic \
  --analyze-tools

# Submit analysis via MCP protocol
python scripts/mcp_client_demo.py \
  --server-type basic \
  --input examples/data/sample.fasta

# Test async job management
python scripts/mcp_client_demo.py \
  --server-type queue \
  --input examples/data/sample.fasta \
  --save-results mcp_test_results.json

MCP服务器安装

选项1：使用fastmcp（推荐）

# Install MCP server for Claude Code
fastmcp install src/server.py --name bio-mcp-interpro

选项2:Claude代码的手动安装

# Add MCP server to Claude Code
claude mcp add bio-mcp-interpro -- $(pwd)/env/bin/python $(pwd)/src/server.py

# Verify installation
claude mcp list

选项3：在settings.json中配置

增添 ~/.claude/settings.json:

{
  "mcpServers": {
    "bio-mcp-interpro": {
      "command": "/home/xux/Desktop/ProteinMCP/ProteinMCP/tool-mcps/interpro_mcp/env/bin/python",
      "args": ["/home/xux/Desktop/ProteinMCP/ProteinMCP/tool-mcps/interpro_mcp/src/server.py"]
    }
  }
}

使用Claude代码

安装MCP服务器后，您可以直接在Claude Code中使用它。

快速开始

# Start Claude Code
claude

示例提示

工具发现

What tools are available from bio-mcp-interpro?

基本分析

Use analyze_protein_sequence with input_file @examples/data/sample.fasta

使用自定义参数

Run analyze_protein_sequence on @examples/data/sample.fasta with output_format "json" and databases "Pfam,SMART"

长期运行任务（提交API）

Submit protein analysis for @examples/data/large_dataset.fasta
Then check the job status

批处理

Submit batch protein analysis for these files:
- @examples/data/sample.fasta
- @examples/data/small_dataset.fasta
- @examples/data/large_dataset.fasta

工作管理

List all jobs currently running
Get results for job ID "abc12345"
Cancel job "xyz789"

使用@引用

在克劳德代码中，使用 @ 引用文件和目录：

参考	说明
`@examples/data/sample.fasta`	参考特定的FASTA文件
`@configs/default_config.json`	引用配置文件
`@results/`	参考输出目录

与Gemini CLI一起使用

配置

增添 ~/.gemini/settings.json:

{
  "mcpServers": {
    "bio-mcp-interpro": {
      "command": "/home/xux/Desktop/ProteinMCP/ProteinMCP/tool-mcps/interpro_mcp/env/bin/python",
      "args": ["/home/xux/Desktop/ProteinMCP/ProteinMCP/tool-mcps/interpro_mcp/src/server.py"]
    }
  }
}

示例提示

# Start Gemini CLI
gemini

# Example prompts (same as Claude Code)
> What tools are available?
> Use analyze_protein_sequence with file examples/data/sample.fasta
> Submit batch analysis for multiple protein files

可用工具

快速操作（同步API）

这些工具会立即返回结果（<10分钟）：

工具	说明	参数
`analyze_protein_sequence`	基础蛋白质结构域分析	`input_file`, `output_format`, `databases`, `output_file`
`create_sample_data`	生成测试蛋白序列	`output_file`, `sequence_count`, `sequence_type`

长期运行任务（提交API）

这些工具返回一个job_id进行跟踪（>10分钟）：

工具	说明	参数
`submit_protein_analysis`	提交域分析作业	`input_file`, `output_format`, `databases`, `output_dir`, `job_name`
`submit_batch_protein_analysis`	提交批量分析	`input_files`, `output_format`, `databases`, `output_dir`, `job_name`
`submit_large_dataset_analysis`	提交带有作业队列的大型数据集	`input_file`, `priority`, `notification_email`, `output_dir`, `job_name`

作业管理工具

工具	说明
`get_job_status`	检查作业进度
`get_job_result`	完成后获取结果
`get_job_log`	查看执行日志
`cancel_job`	取消正在运行的作业
`list_jobs`	列出所有作业
`get_server_info`	获取服务器统计信息

例子

示例1：基本蛋白质分析

目标： 分析一个小的蛋白质数据集进行结构域识别

使用脚本：

python scripts/protein_domain_scan.py \
  --input examples/data/sample.fasta \
  --output results/example1/ \
  --format tsv

使用MCP（克劳德代码）：

Use analyze_protein_sequence to process @examples/data/sample.fasta and save results with output_format "tsv"

预期产量：

域和族注释
GO学期作业
带有解析结果的结构化JSON摘要
原始InterProScan TSV输出

示例2：大数据集处理

目标： 提交大型蛋白质数据集进行背景处理

使用脚本：

python scripts/async_job_manager.py \
  --submit \
  --input examples/data/large_dataset.fasta \
  --priority 8 \
  --email researcher@university.edu

使用MCP（克劳德代码）：

Submit large dataset analysis for @examples/data/large_dataset.fasta with priority 8 and notification_email "researcher@university.edu"

预期产量：

用于跟踪进度的作业ID
带有状态更新的后台处理
完成时发送电子邮件通知
确定所有领域/家族的综合结果

示例3：批处理

目标： 一次处理多个文件

使用脚本：

for f in examples/data/*.fasta; do
  python scripts/async_job_manager.py \
    --submit \
    --input "$f" \
    --priority 5
done

使用MCP（克劳德代码）：

Submit batch processing for these files:
- @examples/data/sample.fasta
- @examples/data/small_dataset.fasta
- @examples/data/large_dataset.fasta

预期产量：

具有多个输入文件的单个批处理作业
综合进度跟踪
所有输入的统一结果结构

演示数据

这 examples/data/ 目录包含用于测试的示例数据：

文件	描述	与一起使用
`sample.fasta`	4个具有已知结构域的蛋白质序列	`analyze_protein_sequence`，基本测试
`small_dataset.fasta`	UniProt的3个真实蛋白质序列	中等规模测试
`large_dataset.fasta`	50+合成蛋白序列	`submit_large_dataset_analysis`
`config_example.yaml`	服务器配置模板	脚本配置

配置文件

这 configs/ 目录包含配置模板：

配置	描述	参数
`default_config.json`	默认服务器设置	InterPro路径、超时、输出格式
`protein_domain_scan_config.json`	域扫描特定配置	数据库选择、分析参数
`async_job_manager_config.json`	作业管理配置	队列设置、优先级处理
`mcp_client_demo_config.json`	MCP客户端设置	服务器端点、连接参数

配置示例

{
  "interpro_path": "interproscan.sh",
  "default_databases": ["Pfam", "SMART", "Gene3D", "SUPERFAMILY"],
  "timeout_seconds": 3600,
  "output_formats": ["tsv", "xml", "json", "gff3"],
  "max_concurrent_jobs": 4,
  "job_priority_levels": 10
}

故障排除

环境问题

问题： 未找到环境

# Recreate environment
mamba create -p ./env python=3.10 -y
mamba activate ./env
pip install loguru click pandas numpy tqdm
pip install "mcp>=1.1.0" "pydantic>=2.0.0" "httpx>=0.24.0"
pip install fastmcp --force-reinstall --no-cache-dir

问题： 导入错误

# Verify installation
python -c "from src.server import mcp; print('✓ MCP server imported successfully')"

问题： MCP兼容性问题

# Check MCP version compatibility
python -c "import mcp; print('MCP available')"
# Note: Repository uses mock implementation due to MCP version differences

MCP问题

问题： 在Claude代码中找不到服务器

# Check MCP registration
claude mcp list

# Re-add if needed
claude mcp remove bio-mcp-interpro
claude mcp add bio-mcp-interpro -- $(pwd)/env/bin/python $(pwd)/src/server.py

问题： 工具不工作

# Test server directly
python src/server.py --help
# Check if server starts without errors

问题： FastMCP安装问题

# Reinstall FastMCP
pip uninstall fastmcp -y
pip install fastmcp --force-reinstall --no-cache-dir

工作问题

问题： 作业挂起

# Check job directory
ls -la jobs/

# View job metadata
cat jobs/jobs_metadata.json

问题： 作业失败

Use get_job_log with job_id "<job_id>" and tail 100 to see error details

问题： 未找到InterProScan

默认情况下，系统以模拟模式运行
单独安装InterProScan进行真正的蛋白质分析
模拟模式演示所有功能，无需InterProScan

性能问题

问题： 作业处理缓慢

# Check system resources
top -p $(pgrep -f "python.*server.py")

# Review job logs for bottlenecks
tail -f jobs/<job_id>/job.log

问题： 大型数据集的内存问题

考虑将大型FASTA文件拆分为更小的块
对多个文件使用批处理工具
监控作业执行期间的内存使用情况

发展

运行测试

# Activate environment
mamba activate ./env

# Run integration tests
python tests/run_integration_tests.py

# Run MCP server tests
python tests/test_mcp_server.py

正在启动开发服务器

# Run MCP server in development mode
python src/server.py

# Or using fastmcp
fastmcp dev src/server.py

代码质量

# Format code
ruff format src/ scripts/

# Lint code
ruff check src/ scripts/

许可证

此项目基于bio-mcp interc存储库构建，并遵循相同的许可条款。

学分

基于 bio-mcp接口存储库。通过全面的MCP集成、作业管理和批处理功能得到增强。

支持

关于问题和支持：

检查上面的故障排除部分
在中查看作业日志 jobs/ 目录
首先使用演示数据进行测试
验证环境设置是否符合要求

版本信息

MCP服务器版本: 1.0.0
FastMCP版本: 2.14.1
Python版本: 3.10.19
创建: 2025-12-21

使用说明

bio-mcp层间mcp

目录

概述

特性

目录结构

安装

快速设置（推荐）

先决条件

手动安装（替代）

本地使用（脚本）

可用脚本

脚本示例

蛋白质结构域扫描

异步作业管理器

MCP客户端演示

MCP服务器安装

选项1：使用fastmcp（推荐）

选项2:Claude代码的手动安装

选项3：在settings.json中配置

使用Claude代码

快速开始

示例提示

工具发现

基本分析

使用自定义参数

长期运行任务（提交API）

批处理

工作管理

使用@引用

与Gemini CLI一起使用

配置

示例提示

可用工具

快速操作（同步API）

长期运行任务（提交API）

作业管理工具

例子

示例1：基本蛋白质分析

示例2：大数据集处理

示例3：批处理

演示数据

配置文件

配置示例

故障排除

环境问题

MCP问题

工作问题

性能问题

发展

运行测试

正在启动开发服务器

代码质量

许可证

学分

支持

版本信息

相关 MCP

生物信息学工具服务器

生物数据查询服务

基因集富集分析服务器

质粒数据协议服务

单细胞RNA测序数据查询服务

线虫基因组查询服务