Installation Guide¶

This guide covers different ways to install and set up the EDAM MCP Server.

🚀 Quick Installation¶

Prerequisites¶

Python 3.12+: The server requires Python 3.12 or higher
uv (recommended): Fast Python package manager
Git: For cloning the repository

Option 1: Using uv (Recommended)¶

# Clone the repository
git clone https://github.com/your-username/edammcp.git
cd edammcp

# Install with uv
uv sync --dev

# Install in development mode
uv pip install -e .

Option 2: Using pip¶

# Clone the repository
git clone https://github.com/your-username/edammcp.git
cd edammcp

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

# Install dependencies
pip install -e .

Option 3: Using conda¶

# Clone the repository
git clone https://github.com/your-username/edammcp.git
cd edammcp

# Create conda environment
conda create -n edammcp python=3.12
conda activate edammcp

# Install dependencies
pip install -e .

🔧 Development Installation¶

For development work, install with all development dependencies:

# Install development dependencies
uv sync --dev

# Install in development mode
uv pip install -e .

# Verify installation
uv run python examples/simple_test.py

📦 Package Installation¶

From PyPI (when available)¶

pip install edam-mcp-server

From Source¶

# Clone and install
git clone https://github.com/your-username/edammcp.git
cd edammcp
pip install .

🐳 Docker Installation¶

Using Docker¶

# Build the image
docker build -t edam-mcp-server .

# Run the container
docker run -p 8000:8000 edam-mcp-server

Using Docker Compose¶

# docker-compose.yml
version: '3.8'
services:
  edam-mcp:
    build: .
    ports:
      - "8000:8000"
    environment:
      - EDAM_LOG_LEVEL=INFO
    volumes:
      - ./data:/app/data

# Run with docker-compose
docker-compose up -d

🔍 Verification¶

Test Basic Functionality¶

# Test basic imports and server creation
uv run python examples/simple_test.py

Expected output:

✅ Basic imports successful
✅ Server creation successful
✅ Configuration loading successful

Test Full Functionality¶

# Test with ML models (downloads on first run)
uv run python examples/basic_usage.py

Expected output:

✅ Ontology loading successful
✅ Concept mapping successful
✅ Concept suggestion successful

Test MCP Server¶

# Start the MCP server
uv run python -m edam_mcp.main

⚙️ Configuration¶

Environment Variables¶

Create a .env file in the project root:

# EDAM Ontology Configuration
EDAM_ONTOLOGY_URL=https://raw.githubusercontent.com/edamontology/edamontology/master/EDAM_dev.owl

# Matching Configuration
EDAM_SIMILARITY_THRESHOLD=0.7
EDAM_MAX_SUGGESTIONS=5

# Model Configuration
EDAM_EMBEDDING_MODEL=all-MiniLM-L6-v2

# Cache Configuration
EDAM_CACHE_TTL=3600

# Logging Configuration
EDAM_LOG_LEVEL=INFO

Configuration File¶

You can also use a configuration file:

# config.py
from edam_mcp.config import Settings

settings = Settings(
    edam_ontology_url="https://raw.githubusercontent.com/edamontology/edamontology/master/EDAM_dev.owl",
    similarity_threshold=0.7,
    max_suggestions=5,
    embedding_model="all-MiniLM-L6-v2",
    cache_ttl=3600,
    log_level="INFO"
)

🚀 First Run¶

1. Start the Server¶

# Basic start
uv run python -m edam_mcp.main

# With custom configuration
EDAM_LOG_LEVEL=DEBUG uv run python -m edam_mcp.main

2. Test with MCP Client¶

Configure your MCP client (e.g., Claude Desktop):

{
  "mcpServers": {
    "edam-mcp": {
      "command": "uv",
      "args": ["run", "python", "-m", "edam_mcp.main"],
      "env": {
        "EDAM_LOG_LEVEL": "INFO"
      }
    }
  }
}

3. Test Tools¶

Once connected, test the available tools:

map_to_edam_concept: Map descriptions to EDAM concepts
suggest_new_concept: Suggest new concepts

🔧 Troubleshooting¶

Common Issues¶

1. Python Version Issues¶

# Check Python version
python --version

# Should be 3.12 or higher
# If not, install Python 3.12+

2. Dependency Issues¶

# Clear and reinstall dependencies
rm -rf .venv/
uv sync --dev
uv pip install -e .

3. ML Model Download Issues¶

# Clear model cache
rm -rf ~/.cache/torch/
rm -rf ~/.cache/huggingface/

# Use smaller model
export EDAM_EMBEDDING_MODEL="all-MiniLM-L6-v2"

4. Memory Issues¶

# Reduce memory usage
export EDAM_MAX_SUGGESTIONS=3
export EDAM_SIMILARITY_THRESHOLD=0.8

5. Network Issues¶

# Use local ontology file
export EDAM_ONTOLOGY_URL="file:///path/to/local/edam.owl"

Getting Help¶

GitHub Issues: Create an issue for bugs
Discussions: Use GitHub Discussions for questions
Documentation: Check the docs folder
Examples: Look at the examples folder

📊 System Requirements¶

Minimum Requirements¶

CPU: 2 cores
RAM: 2GB
Storage: 1GB free space
Network: Internet connection

Recommended Requirements¶

CPU: 4+ cores
RAM: 4GB+
Storage: 2GB+ free space
Network: Stable internet connection

Performance Notes¶

First Run: ~5 seconds (ML model download)
Subsequent Runs: <1 second
Memory Usage: ~500MB with models loaded
Concurrent Requests: Full async support

🔄 Updates¶

Updating the Installation¶

# Pull latest changes
git pull origin main

# Update dependencies
uv sync --dev

# Reinstall package
uv pip install -e .

Checking for Updates¶

# Check for outdated packages
uv pip list --outdated

# Update specific package
uv pip install --upgrade package-name

🧹 Uninstallation¶

Remove Package¶

# Remove installed package
pip uninstall edam-mcp-server

# Or with uv
uv pip uninstall edam-mcp-server

Clean Environment¶

# Remove virtual environment
rm -rf .venv/

# Remove cached models
rm -rf ~/.cache/torch/
rm -rf ~/.cache/huggingface/

# Remove project files
rm -rf edammcp/

📚 Next Steps¶

After installation:

Read the Quick Start Guide to get running quickly
Check the Configuration Guide for advanced setup
Explore Examples for usage patterns
Review API Documentation for detailed reference
Join the Community for support