docs/SETUP.md

Setup Guide - OpenProblems Spatial Transcriptomics MCP Server

This guide will help you set up and run the OpenProblems Spatial Transcriptomics MCP Server.

Prerequisites

System Requirements

• Python: 3.8 or higher
• Operating System: Linux, macOS, or Windows (with WSL2 recommended)
• Memory: Minimum 4GB RAM (8GB+ recommended for processing large datasets)
• Storage: 10GB+ free space for data and temporary files

Required Tools

The MCP server integrates with these bioinformatics tools:

• Nextflow: Workflow orchestration
• Viash: Component framework
• Docker: Containerization
• Java: 11 or higher (required for Nextflow)

Installation

Option 1: Local Installation

1. Clone the repository:

   git clone https://github.com/openproblems-bio/SpatialAI_MCP.git
   cd SpatialAI_MCP
   

2. Create a Python virtual environment:

   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   

3. Install the package:

   pip install -e .
   

4. Install external tools:

   Nextflow:

   curl -s https://get.nextflow.io | bash
   sudo mv nextflow /usr/local/bin/
   

   Viash:

   curl -fsSL get.viash.io | bash -s -- --bin /usr/local/bin
   

   Docker: Follow the official Docker installation guide

Option 2: Docker Installation

1. Clone the repository:

   git clone https://github.com/openproblems-bio/SpatialAI_MCP.git
   cd SpatialAI_MCP
   

2. Build the Docker image:

   docker build -f docker/Dockerfile -t openproblems-spatial-mcp .
   

3. Run with Docker Compose:

   cd docker
   docker-compose up -d
   

Option 3: Development Setup

For contributors and developers:

1. Clone and install in development mode:

   git clone https://github.com/openproblems-bio/SpatialAI_MCP.git
   cd SpatialAI_MCP
   pip install -e ".[dev]"
   

2. Install pre-commit hooks:

   pre-commit install
   

3. Run tests:

   pytest tests/
   

Configuration

Basic Configuration

The server uses config/server_config.yaml for configuration. Key settings:

server:
  name: "OpenProblems-SpatialAI-MCP"
  transport:
    primary: "stdio"
    http_port: 8000

paths:
  data_dir: "./data"
  work_dir: "./work"
  logs_dir: "./logs"

tools:
  nextflow:
    default_profile: "docker"
  viash:
    default_engine: "docker"

Environment Variables

You can override configuration with environment variables:

export MCP_SERVER_NAME="Custom-MCP-Server"
export MCP_DATA_DIR="/custom/data/path"
export MCP_LOG_LEVEL="DEBUG"

Directory Structure

Create the required directories:

mkdir -p data work logs cache
chmod 755 data work logs cache

Running the Server

Method 1: Direct Python Execution

# Start the server
python -m mcp_server.main

# Or use the installed command
openproblems-mcp

Method 2: Docker

# Run the container
docker run -it --rm \
  -v $(pwd)/data:/app/data \
  -v $(pwd)/work:/app/work \
  -v $(pwd)/logs:/app/logs \
  -v /var/run/docker.sock:/var/run/docker.sock \
  openproblems-spatial-mcp

Method 3: Docker Compose

cd docker
docker-compose up

Testing the Installation

Run the Test Suite

pytest tests/ -v

Use the Example Client

python examples/simple_client.py

Manual Testing

1. Start the server (in one terminal):

   python -m mcp_server.main
   

2. Test with MCP client (in another terminal):

   import asyncio
   from mcp import ClientSession, StdioServerParameters
   from mcp.client.stdio import stdio_client
   
   async def test_connection():
       server_params = StdioServerParameters(
           command="python",
           args=["-m", "mcp_server.main"],
       )
   
       async with stdio_client(server_params) as (read, write):
           async with ClientSession(read, write) as session:
               await session.initialize()
   
               # Test echo
               result = await session.call_tool("echo_test", {"message": "Hello!"})
               print(f"Echo result: {result}")
   
               # List resources
               resources = await session.list_resources()
               print(f"Available resources: {len(resources)}")
   
   asyncio.run(test_connection())
   

Troubleshooting

Common Issues

1. Import errors:

   • Ensure the package is installed: pip install -e .
   • Check Python path: python -c "import mcp_server; print('OK')"

2. Tool not found errors:

   • Install missing tools (Nextflow, Viash, Docker)
   • Check PATH: which nextflow, which viash, which docker

3. Permission errors:

   • Ensure Docker daemon is running: docker version
   • Check directory permissions: ls -la data/ work/ logs/

4. Port conflicts (HTTP transport):

   • Change port in config: transport.http_port: 8001
   • Check port usage: netstat -tulpn | grep 8000

Debug Mode

Enable debug logging:

export MCP_LOG_LEVEL=DEBUG
python -m mcp_server.main

Log Files

Check server logs:

tail -f logs/mcp_server.log

Health Check

Test server health:

# For Docker containers
docker exec openproblems-spatial-mcp python -c "import mcp; print('MCP SDK available')"

# For local installation
python -c "import mcp_server.main; print('Server module available')"

Next Steps

1. Read the API Documentation to understand available tools and resources
2. Explore Examples to see practical usage patterns
3. Check the Integration Guide for AI agent setup
4. Review Best Practices for optimal usage

Support

• Issues: GitHub Issues
• Documentation: Project Docs
• Community: OpenProblems Discussions

Contributing

See CONTRIBUTING.md for development guidelines and contribution instructions.