MCP Server

The Immunopipe MCP Server is a Model Context Protocol (MCP) server that provides intelligent configuration generation for immunopipe pipelines. It allows AI assistants like Claude to understand and generate complex TOML configuration files for single-cell RNA-seq and TCR/BCR analysis workflows.

Overview

The MCP server exposes a comprehensive set of tools for:

  • Discovery: List available pipeline options, processes, and Google Batch configurations
  • Generation: Create TOML configuration files, templates, and process-specific configs
  • Manipulation: Merge, validate, and format configuration files
  • AI-Assisted Configuration: Generate configurations from natural language descriptions

Installation

The MCP server is included with immunopipe. You can run it directly using:

# Run with stdio transport (for VSCode/Claude integration)
immunopipe mcp --transport stdio

# Run with HTTP transport (for testing)
immunopipe mcp --transport http --port 8000

VSCode Integration

To integrate with VSCode and Claude, add the following to your VSCode settings:

{
  "mcp": {
    "servers": {
      "immunopipe": {
        "command": "python",
        "args": ["-m", "immunopipe.mcp", "--transport", "stdio"]
      }
    }
  }
}

Available Tools

Discovery Tools

list_pipeline_options

Lists all available pipeline-level configuration options.

Parameters: None

Returns: Dictionary of pipeline options with descriptions, types, defaults, and requirements.

list_processes

Lists all available immunopipe processes.

Parameters: None

Returns: Dictionary of processes with descriptions, environment variables, and requirements.

list_gbatch_options

Lists all Google Batch configuration options.

Parameters: None

Returns: Dictionary of Google Batch options with descriptions, types, and defaults.

get_process_details

Gets detailed information about a specific process.

Parameters: - process_name (string): Name of the process to get details for

Returns: Detailed process information including configuration options.

Generation Tools

generate_full_config

Generates a complete immunopipe TOML configuration file.

Parameters: - pipeline_options (object, optional): Pipeline-level options - processes (object, optional): Process configurations - gbatch_options (object, optional): Google Batch options - description (string, optional): Description for the configuration file

Returns: Complete TOML configuration as a string.

generate_pipeline_config

Generates pipeline-level configuration section.

Parameters: - options (object): Pipeline options to include

Returns: Pipeline configuration TOML section.

generate_process_config

Generates configuration for a specific process.

Parameters: - process_name (string): Name of the process - config (object): Process configuration options

Returns: Process configuration TOML section.

generate_gbatch_config

Generates Google Batch configuration section.

Parameters: - options (object): Google Batch options

Returns: Google Batch configuration TOML section.

Template Tools

generate_basic_template

Generates a basic immunopipe configuration template.

Parameters: None

Returns: Basic TOML template suitable for standard scRNA-seq analysis.

generate_tcr_template

Generates a template optimized for TCR analysis.

Parameters: None

Returns: TOML template configured for single-cell TCR/BCR analysis.

generate_gbatch_template

Generates a template for Google Batch execution.

Parameters: None

Returns: TOML template configured for cloud execution via Google Batch.

Manipulation Tools

merge_configs

Merges two TOML configuration files or strings.

Parameters: - base_config (string): Base configuration (TOML string) - new_config (string): New configuration to merge (TOML string)

Returns: Merged TOML configuration.

validate_config

Validates a TOML configuration file.

Parameters: - config_content (string): TOML configuration content to validate

Returns: Validation results with success status and error messages.

format_config

Formats and enhances a TOML configuration.

Parameters: - config_content (string): TOML configuration content to format - add_comments (boolean, optional): Whether to add helpful comments

Returns: Formatted TOML configuration with optional comments.

AI-Assisted Tools

configure_immunopipe

Generates immunopipe configuration from natural language requirements. This is the most intelligent tool that can understand complex analysis requirements and automatically select appropriate processes.

Parameters: - requirements (string): Natural language description of analysis needs - specific_processes (array, optional): Specific process names to configure - parameters (object, optional): Specific parameter values to set

Examples: - "clustering with resolution 0.5" - "TCR analysis with clustering" - "set SeuratPreparing QC parameters"

Returns: Complete TOML configuration tailored to the requirements.

help_generate_config

Provides configuration suggestions based on natural language descriptions.

Parameters: - description (string): Natural language description of analysis goals

Returns: Suggestions and recommended tools for the analysis.

suggest_processes

Suggests processes based on analysis type.

Parameters: - analysis_type (string): Type of analysis (e.g., 'tcr', 'bcr', 'clustering', 'differential')

Returns: List of recommended processes for the analysis type.

Usage Examples

Basic Usage

from immunopipe.mcp.tools import ImmunopipeConfigTools

# Initialize the tools
tools = ImmunopipeConfigTools()

# Generate a basic template
result = await tools.generate_basic_template()
print(result.content)

Natural Language Configuration

# Configure immunopipe using natural language
result = await tools.configure_immunopipe(
    requirements="I want to analyze single-cell TCR data with clustering resolution 0.8"
)
print(result.content)  # Complete TOML configuration

Process Discovery

# List available processes
processes = await tools.list_processes()
print(f"Found {len(processes.content)} processes")

# Get details for a specific process
details = await tools.get_process_details("SeuratClustering")
print(details.content)

Configuration Manipulation

# Generate base config
base = await tools.generate_basic_template()

# Generate TCR-specific additions
tcr_config = await tools.generate_tcr_template()

# Merge configurations
merged = await tools.merge_configs(base.content, tcr_config.content)
print(merged.content)

Integration with Claude/AI Assistants

The MCP server is designed to work seamlessly with AI assistants. With immunopipe installed, you can add the MCP server to your Claude or VSCode setup to enable intelligent configuration generation:

claude mcp add --transport http immunopipe-mcp http://localhost:80000

{
  "mcp": {
    "servers": {
        "immunopipe": {
            "command": "python",
            "args": ["-m", "immunopipe", "mcp", "--transport", "stdio"]
        }
    }
}

Here are some example prompts that work well:

Configuration Generation

  • "Generate an immunopipe configuration for TCR analysis"
  • "Create a config for single-cell clustering with resolution 0.5"
  • "Set up immunopipe for differential expression analysis"

Process Selection

  • "What processes do I need for BCR analysis?"
  • "Suggest processes for clustering analysis"
  • "Show me options for Google Batch execution"

Configuration Management

  • "Validate this immunopipe configuration"
  • "Format and add comments to my config file"
  • "Merge these two immunopipe configurations"

Architecture

The MCP server consists of several key components:

  • McpServer: Main server implementation with JSON-RPC over HTTP
  • MCPServer: Standards-compliant MCP server for VSCode integration
  • ImmunopipeConfigTools: Core tool collection with hierarchical capabilities
  • OptionsDiscovery: Discovers available configuration options and processes
  • TOMLGenerator: Generates and manipulates TOML configuration files
  • ProcessDocumentationExtractor: Extracts process documentation for intelligent configuration

Error Handling

The MCP server provides comprehensive error handling:

  • Tool Validation: Validates tool parameters and provides helpful error messages
  • Configuration Validation: Checks TOML syntax and immunopipe-specific requirements
  • Process Discovery: Handles missing or unavailable processes gracefully
  • Natural Language Processing: Provides fallback configurations when analysis fails

Development and Testing

To test the MCP server locally:

# Run the example demonstration
python -m immunopipe.mcp.example

# Run interactive demo
python -m immunopipe.mcp.example interactive

# Test with HTTP transport
immunopipe mcp --transport http --port 8000

The server includes comprehensive test coverage and example usage patterns to help with development and integration.

Performance

The MCP server is optimized for:

  • Fast Discovery: Efficient caching of process and option information
  • Incremental Configuration: Tools can be chained for complex configurations
  • Memory Efficiency: Lazy loading of process documentation
  • Scalability: Async/await support for concurrent tool execution

Support and Troubleshooting

Common issues and solutions:

  1. Process Not Found: Ensure immunopipe is properly installed and processes are available
  2. Configuration Validation Errors: Check TOML syntax and parameter validity
  3. Natural Language Analysis Failures: Use more specific descriptions or explicit process names
  4. VSCode Integration Issues: Verify MCP server configuration in VSCode settings

For additional help, open an issue on the GitHub repository.