Bio-MCP FastQC Server

Fornece controle de qualidade para dados de sequências biológicas usando as ferramentas FastQC e MultiQC.

GitHub

Documentação

Servidor Bio-MCP FastQC 🔬

Análise de Controle de Qualidade via Protocolo de Contexto de Modelo

Um servidor MCP que permite que assistentes de IA executem análises de controle de qualidade FastQC e MultiQC em dados de sequenciamento. Parte do ecossistema Bio-MCP.

🎯 Propósito

O FastQC é essencial para a avaliação da qualidade de dados de sequenciamento de alto rendimento. Este servidor MCP permite que assistentes de IA:

  • Analisem arquivos individuais - Obtenham relatórios detalhados de QC para arquivos FASTQ/FASTA individuais
  • Processamento em lote - Executem QC em múltiplos arquivos simultaneamente
  • Gerem relatórios resumidos - Criem relatórios MultiQC combinando múltiplas análises
  • Lidem com grandes conjuntos de dados - Suporte a sistema de fila para trabalhos computacionalmente intensivos

🚀 Início Rápido

Pré-requisitos

Instale FastQC e MultiQC:

# Via conda (recommended)
conda install -c bioconda fastqc multiqc

# Via package managers
# Ubuntu/Debian
sudo apt-get install fastqc
pip install multiqc

# macOS
brew install fastqc
pip install multiqc

Instalação

# Clone and install
git clone https://github.com/bio-mcp/bio-mcp-fastqc.git
cd bio-mcp-fastqc
pip install -e .

# Or install directly
pip install git+https://github.com/bio-mcp/bio-mcp-fastqc.git

Configuração do Claude Desktop

Adicione ao seu claude_desktop_config.json:

{
  "mcpServers": {
    "bio-fastqc": {
      "command": "python",
      "args": ["-m", "src.server"],
      "cwd": "/path/to/bio-mcp-fastqc"
    }
  }
}

🔧 Ferramentas Disponíveis

Ferramentas de Análise Principal

fastqc_single

Execute FastQC em um único arquivo FASTQ/FASTA.

Parâmetros:

  • input_file (obrigatório): Caminho para o arquivo FASTQ ou FASTA
  • threads (opcional): Número de threads (padrão: 1)
  • contaminants (opcional): Caminho para arquivo de contaminantes personalizado
  • adapters (opcional): Caminho para arquivo de adaptadores personalizado
  • limits (opcional): Caminho para arquivo de limites personalizado

Exemplo:

User: "Run quality control on my_sample.fastq.gz"
AI: [calls fastqc_single] → Returns detailed QC report with pass/warn/fail status for each module

fastqc_batch

Execute FastQC em múltiplos arquivos em um diretório.

Parâmetros:

  • input_dir (obrigatório): Diretório contendo arquivos FASTQ/FASTA
  • file_pattern (opcional): Padrão de arquivo para correspondência (padrão: ".fastq")
  • threads (opcional): Número de threads (padrão: 4)

Exemplo:

User: "Analyze all fastq files in the data/ directory"
AI: [calls fastqc_batch] → Processes all files and returns summary statistics

multiqc_report

Gere relatório MultiQC a partir dos resultados do FastQC.

Parâmetros:

  • input_dir (obrigatório): Diretório contendo FastQC e outros resultados de análise
  • title (opcional): Título personalizado para o relatório
  • comment (opcional): Comentário a ser adicionado ao relatório
  • template (opcional): Modelo de relatório (padrão, simples, seções, agrupado)

Exemplo:

User: "Create a summary report from all the QC results"
AI: [calls multiqc_report] → Generates interactive HTML report combining all analyses

Ferramentas do Sistema de Fila (quando a fila está habilitada)

Para grandes conjuntos de dados ou processamento em lote:

  • fastqc_single_async - Colocar análise de arquivo único na fila
  • fastqc_batch_async - Colocar análise em lote na fila
  • multiqc_report_async - Colocar geração de relatório na fila
  • get_job_status - Verificar progresso do trabalho
  • get_job_result - Recuperar resultados concluídos
  • cancel_job - Cancelar trabalhos em execução

💡 Exemplos de Uso

Avaliação Básica de Qualidade

User: "What's the quality of my sequencing data in sample1.fastq.gz?"

AI Response:
✅ FastQC Analysis Complete for sample1

Module Status Summary:
✅ Basic Statistics: PASS
✅ Per base sequence quality: PASS
⚠️ Per sequence quality scores: WARN
✅ Per base sequence content: PASS
✅ Per sequence GC content: PASS
✅ Per base N content: PASS
✅ Sequence Length Distribution: PASS
❌ Sequence Duplication Levels: FAIL
✅ Overrepresented sequences: PASS
✅ Adapter Content: PASS

Basic Statistics:
• Total Sequences: 2,450,000
• Sequences flagged as poor quality: 0
• Sequence length: 150
• %GC: 47

Análise em Lote

User: "Analyze all FASTQ files in my project/raw_data/ folder"

AI Response:
FastQC Batch Analysis Complete
========================================

Processed 12 files:

✅ sample01_R1.fastq.gz: 8P/2W/0F
✅ sample01_R2.fastq.gz: 8P/2W/0F
⚠️ sample02_R1.fastq.gz: 7P/2W/1F
⚠️ sample02_R2.fastq.gz: 7P/2W/1F
...

Overall Summary:
• Total PASS: 94
• Total WARN: 24
• Total FAIL: 2

Tip: Run multiqc_report on this directory to generate a combined report!

Fluxo de Trabalho Completo

User: "I have a directory of paired-end FASTQ files. Can you run quality control and create a summary report?"

AI: I'll run a complete QC workflow on your paired-end data:

1. First, let me analyze all FASTQ files in batch:
   [runs fastqc_batch on directory]

2. Now I'll generate a MultiQC summary report:
   [runs multiqc_report on results]

✅ Complete QC workflow finished!

Summary:
- 24 FASTQ files processed (12 samples, paired-end)
- Average quality score: 32.5
- 2 samples have adapter contamination warnings
- 1 sample shows high duplication levels
- Interactive HTML report generated: multiqc_report.html

The MultiQC report provides detailed visualizations of:
- Quality score distributions across all samples
- GC content comparison
- Sequence length distributions
- Adapter content analysis
- Sample correlation analysis

🐳 Uso com Docker

Construir e Executar

# Build the image
docker build -t bio-mcp-fastqc .

# Run with data mounting
docker run -v /path/to/data:/data bio-mcp-fastqc

Docker Compose (com Sistema de Fila)

services:
  fastqc-server:
    build: .
    volumes:
      - ./data:/data
    environment:
      - BIO_MCP_QUEUE_URL=http://queue-api:8000
    depends_on:
      - queue-api

⚙️ Configuração

Variáveis de Ambiente

  • BIO_MCP_FASTQC_PATH - Caminho para o executável FastQC (padrão: "fastqc")
  • BIO_MCP_MULTIQC_PATH - Caminho para o executável MultiQC (padrão: "multiqc")
  • BIO_MCP_MAX_FILE_SIZE - Tamanho máximo de arquivo em bytes (padrão: 10GB)
  • BIO_MCP_TIMEOUT - Tempo limite de comando em segundos (padrão: 1800)
  • BIO_MCP_TEMP_DIR - Diretório temporário para processamento

Integração com Sistema de Fila

Para habilitar processamento assíncrono para grandes conjuntos de dados:

from src.server_with_queue import FastQCServerWithQueue

server = FastQCServerWithQueue(queue_url="http://localhost:8000")

📊 Arquivos de Saída

O FastQC gera vários arquivos de saída:

  • Relatório HTML (*_fastqc.html) - Relatório de qualidade interativo
  • Arquivo de Dados (fastqc_data.txt) - Métricas e estatísticas brutas
  • Arquivo de Resumo (summary.txt) - Status de aprovação/aviso/falha para cada módulo
  • Gráficos - Vários gráficos e tabelas de qualidade

O MultiQC combina estes em:

  • Relatório MultiQC (multiqc_report.html) - Relatório interativo combinado
  • Diretório de Dados (multiqc_data/) - Dados processados e estatísticas
  • Estatísticas Gerais (multiqc_general_stats.txt) - Tabela de resumo

🔍 Métricas de Qualidade Explicadas

O FastQC analisa múltiplos aspectos de qualidade:

Módulos Principais

  • Qualidade da sequência por base - Pontuações de qualidade nas posições de leitura
  • Pontuações de qualidade por sequência - Distribuição das pontuações médias de qualidade
  • Conteúdo da sequência por base - Conteúdo de A/T/G/C nas posições
  • Conteúdo GC por sequência - Distribuição de GC% vs esperado
  • Níveis de duplicação de sequência - Avaliação de duplicação por PCR
  • Conteúdo de adaptadores - Sequências de adaptadores contaminantes

Interpretação de Status

  • ✅ APROVADO - A análise indica nenhum problema
  • ⚠️ AVISO - Ligeiramente incomum, pode não ser problemático
  • ❌ FALHA - Provavelmente problemático, requer atenção

🧬 Integração com o Ecossistema Bio-MCP

O FastQC funciona perfeitamente com outras ferramentas Bio-MCP:

User: "Run the complete preprocessing pipeline on my samples"

AI Workflow:
1. fastqc_batch → Initial quality assessment
2. trimmomatic → Trim low-quality bases and adapters  
3. fastqc_batch → Post-trimming QC
4. multiqc_report → Combined before/after report

🤝 Contribuindo

Aceitamos contribuições! Veja o guia de contribuição do Bio-MCP.

Configuração de Desenvolvimento

git clone https://github.com/bio-mcp/bio-mcp-fastqc.git
cd bio-mcp-fastqc
pip install -e ".[dev]"
pytest

📄 Licença

Licença MIT - veja o arquivo LICENSE.

🙏 Agradecimentos

  • FastQC por Simon Andrews na Babraham Bioinformatics
  • MultiQC por Phil Ewels e a comunidade MultiQC
  • Projeto Bio-MCP e contribuidores

Parte do ecossistema Bio-MCP - Tornando a bioinformática acessível para assistentes de IA.

Para mais ferramentas: Organização Bio-MCP