git clone <your-repo>
cd mcp-server-template
uv venv
source .venv/bin/activate
uv install

source .venv/bin/activate && uv run python -m mcp_server

source .venv/bin/activate && uv run python main.py

# Streamable HTTP transport
export MCP_TRANSPORT=streamable-http
export MCP_PORT=8080
source .venv/bin/activate && uv run python -m mcp_server

# Server-Sent Events transport  
export MCP_TRANSPORT=sse
export MCP_PORT=8081
source .venv/bin/activate && uv run python -m mcp_server

# Run diagnostic test
source .venv/bin/activate && uv run python diagnosis_test.py

# Run verification test
source .venv/bin/activate && uv run python verification_test.py

# Clone the repository
git clone <your-repo-url>
cd mcp-server-template

# Create and activate virtual environment
uv venv
source .venv/bin/activate

# Install dependencies
uv install

# Install development dependencies
uv install --group dev

# Install from source
uv install git+<your-repo-url>

# Or from local directory
uv install .

# Standard streamable HTTP mode
source .venv/bin/activate && uv run python -m mcp_server

# Run as streamable HTTP server
export MCP_TRANSPORT=streamable-http
export MCP_HOST=0.0.0.0
export MCP_PORT=8080
source .venv/bin/activate && uv run python -m mcp_server

# Run as SSE server
export MCP_TRANSPORT=sse
export MCP_HOST=0.0.0.0  
export MCP_PORT=8081
source .venv/bin/activate && uv run python -m mcp_server

# Enable debug logging
export MCP_LOG_LEVEL=DEBUG
export MCP_ENVIRONMENT=development
source .venv/bin/activate && uv run python -m mcp_server

# Build image
docker build -t mcp-server .

# Run container (default mode)
docker run -it mcp-server

# Run container (Streamable HTTP mode)
docker run -e MCP_TRANSPORT=streamable-http -e MCP_PORT=8080 -p 8080:8080 mcp-server

# With custom configuration
docker run -e MCP_LOG_LEVEL=DEBUG -e MCP_ENVIRONMENT=production -it mcp-server

{
  "mcpServers": {
    "mcp-server-template": {
      "command": "uv",
      "args": ["run", "python", "-m", "mcp_server"],
      "cwd": "/path/to/your/mcp-server-template"
    }
  }
}

{
  "mcpServers": {
    "mcp-server-template": {
      "url": "http://localhost:8080/mcp",
      "transport": "streamable-http"
    }
  }
}

mcp-server-template/
├── src/mcp_server/              # Main package (v0.1.0)
│   ├── __init__.py             # Package initialization & lazy imports
│   ├── __main__.py             # Module entry point
│   ├── server.py               # Core FastMCP server implementation
│   ├── config/                 # Configuration management
│   │   ├── __init__.py
│   │   ├── settings.py         # Pydantic settings with environment support
│   │   └── logging.py          # Structured logging configuration
│   ├── tools/                  # MCP tools
│   │   ├── __init__.py
│   │   ├── base.py            # Base tool class
│   │   ├── arithmetic.py       # Arithmetic tools (add, subtract)
│   │   ├── weather.py          # Weather tools (get_current_weather)
│   │   └── registry.py         # Tool auto-discovery registry
│   ├── resources/              # MCP resources
│   │   ├── __init__.py
│   │   ├── base.py            # Base resource class
│   │   ├── system.py          # System information resources
│   │   └── registry.py         # Resource auto-discovery registry
│   └── prompts/                # MCP prompts
│       ├── __init__.py
│       ├── base.py            # Base prompt class
│       ├── text_processing.py  # Text processing prompts
│       └── registry.py         # Prompt auto-discovery registry
├── tests/                      # Test suite
│   ├── conftest.py            # Shared test fixtures
│   ├── unit/                  # Unit tests
│   │   └── test_tools.py
│   └── integration/           # Integration tests
│       └── test_client_interactions.py
├── main.py                     # Backward compatibility entry
├── Dockerfile                  # Container deployment
├── diagnosis_test.py           # Server diagnostic tool
├── verification_test.py        # Server verification tool
└── pyproject.toml             # Project configuration

# Server creation with auto-discovery
from mcp_server import create_server

server = create_server()  # Automatically discovers and registers all components

# Components are automatically found and registered
from mcp_server.tools.registry import register_all_tools
from mcp_server.resources.registry import register_all_resources  
from mcp_server.prompts.registry import register_all_prompts

# Registration happens automatically in create_server()
register_all_tools(mcp)
register_all_resources(mcp)
register_all_prompts(mcp)

# Flexible transport configuration
await mcp.run_async(
    transport=settings.transport,  # streamable-http or sse
    host=settings.host,           # configurable host
    port=settings.port            # configurable port
)

from mcp_server.config.settings import get_settings

settings = get_settings()  # Loads from environment with defaults
# Supports: transport, host, port, log_level, environment, etc.

# src/mcp_server/tools/my_tool.py
from typing import Any
from fastmcp import FastMCP
from .base import BaseTool

class MyTool(BaseTool):
    """Example tool that processes text input."""
    
    def __init__(self):
        super().__init__(name="my_tool")
    
    def register_with_mcp(self, mcp: FastMCP) -> None:
        """Register tools with FastMCP instance."""
        
        @mcp.tool()
        async def process_text(text: str) -> str:
            """Process text input and return formatted result.
            
            Args:
                text: Input text to process
                
            Returns:
                Processed text in uppercase
            """
            self._log_tool_call("process_text", text=text)
            return f"Processed: {text.upper()}"
        
        self.logger.info("Registered my_tool: process_text")

# The tool is automatically discovered by the registry!

from typing import Dict, Any
from fastmcp import FastMCP
from .base import BaseTool

class ValidatedTool(BaseTool):
    """Example tool with validation using FastMCP decorators"""
    
    def __init__(self):
        super().__init__(name="validated")
    
    def register_with_mcp(self, mcp: FastMCP) -> None:
        @mcp.tool()
        async def process_data(value: int, name: str) -> Dict[str, Any]:
            """Process data with validation.
            
            Args:
                value: Integer value to process
                name: Name to include in result
                
            Returns:
                Processed data dictionary
            """
            if not (0 <= value <= 100):
                raise ValueError("Value must be between 0-100")
            if not name or not name.strip():
                raise ValueError("Name cannot be empty")
                
            return {"value": value, "name": name.strip(), "processed": True}
        
        self.logger.info("Registered validated tool: process_data")

# src/mcp_server/resources/my_resource.py
import json
from typing import Any
from .base import BaseResource

class MyResource(BaseResource):
    """Example resource that provides data."""
    
    uri_template = "my://data/{category}"
    name = "My Data Resource"
    description = "Provides categorized data"
    mime_type = "application/json"
    
    async def read(self, category: str = "default") -> str:
        """Read resource data for the given category."""
        data = {
            "category": category,
            "items": [f"item-{i}" for i in range(1, 6)],
            "timestamp": "2024-01-01T00:00:00Z"
        }
        return json.dumps(data, indent=2)

# Automatically discovered by the registry!

# src/mcp_server/prompts/my_prompt.py
from typing import Any, List
from fastmcp import FastMCP
from .base import BasePrompt

class MyPrompt(BasePrompt):
    """Example prompt for content generation."""
    
    def __init__(self):
        super().__init__(name="my_prompt")
    
    def register_with_mcp(self, mcp: FastMCP) -> None:
        """Register prompts with FastMCP instance."""
        
        @mcp.prompt()
        async def generate_content(topic: str, format: str = "markdown") -> str:
            """Generate structured content about a topic.
            
            Args:
                topic: The topic to generate content about
                format: Output format (markdown, text, etc.)
                
            Returns:
                Generated content in the specified format
            """
            self._log_prompt_call("generate_content", topic=topic, format=format)
            
            if format == "markdown":
                return f"""# {topic}
                
## Overview
This is an overview of {topic}.

## Key Points
- Point 1 about {topic}
- Point 2 about {topic}
- Point 3 about {topic}

## Conclusion
Summary of {topic}.
"""
            else:
                return f"Content about {topic} in {format} format"
        
        self.logger.info("Registered my_prompt: generate_content")

# Automatically discovered by the registry!

# All tests
source .venv/bin/activate && uv run pytest

# Unit tests only
source .venv/bin/activate && uv run pytest tests/unit/ -v

# Integration tests only
source .venv/bin/activate && uv run pytest tests/integration/ -v

# Specific test file
source .venv/bin/activate && uv run pytest tests/unit/test_tools.py -v

# With coverage
source .venv/bin/activate && uv run pytest --cov=src/mcp_server --cov-report=html

# Parallel execution
source .venv/bin/activate && uv run pytest -n auto

tests/
├── conftest.py                 # Shared test fixtures
├── unit/                       # Unit tests
│   └── test_tools.py          # Tool testing
└── integration/                # Integration tests
    └── test_client_interactions.py  # End-to-end tests

import pytest
from mcp_server.tools.arithmetic import ArithmeticTools

@pytest.mark.asyncio
async def test_arithmetic_tools():
    tools = ArithmeticTools()
    # Test direct methods
    assert tools.add_numbers(5, 3) == 8
    assert tools.subtract_numbers(10, 4) == 6

@pytest.mark.asyncio
async def test_weather_tools():
    from mcp_server.tools.weather import WeatherTools
    tools = WeatherTools()
    # Weather tool would require proper MCP setup for full testing
    # This is a simplified example
    assert tools._use_mock_data() == True  # Default is mock data

import pytest
from mcp_server import create_server

@pytest.mark.asyncio
async def test_server_creation():
    server = create_server()
    assert server is not None
    
    # Test component registration
    # This would require proper async setup in real tests
    assert server is not None
    
    # Verify tools are available (actual implementation would vary)
    # The server would have add, subtract, get_current_weather tools

export MCP_ENVIRONMENT=development
export MCP_LOG_LEVEL=DEBUG
export MCP_TRANSPORT=streamable-http

export MCP_TRANSPORT=streamable-http
export MCP_HOST=0.0.0.0
export MCP_PORT=8080
export MCP_ENVIRONMENT=production
export MCP_LOG_LEVEL=INFO

export MCP_TRANSPORT=sse
export MCP_HOST=0.0.0.0
export MCP_PORT=8081
export MCP_ENVIRONMENT=production

# src/mcp_server/config/settings.py
from pydantic import BaseModel, Field
from typing import Literal

class Settings(BaseModel):
    # Server Configuration
    server_name: str = "MCP Server Template"
    host: str = "0.0.0.0"
    port: int = 8080
    transport: Literal["streamable-http", "sse"] = "streamable-http"
    
    # Logging Configuration
    log_level: str = "INFO"
    log_format: str = "[%(levelname)s]: %(message)s"
    
    # Environment Configuration
    environment: Literal["development", "production", "testing"] = "development"
    version: str = "0.1.0"
    
    model_config = {
        "env_prefix": "MCP_",
        "case_sensitive": False,
        "env_file": ".env",
        "env_file_encoding": "utf-8"
    }

docker build -t my-mcp-server .

# Default mode
docker run -it my-mcp-server

# Streamable HTTP mode
docker run -e MCP_TRANSPORT=streamable-http -e MCP_HOST=0.0.0.0 -e MCP_PORT=8080 -p 8080:8080 my-mcp-server

# Server-Sent Events mode  
docker run -e MCP_TRANSPORT=sse -e MCP_HOST=0.0.0.0 -e MCP_PORT=8081 -p 8081:8081 my-mcp-server

# With custom environment
docker run -e MCP_LOG_LEVEL=DEBUG -e MCP_ENVIRONMENT=production -it my-mcp-server

version: '3.8'
services:
  mcp-server-default:
    build: .
    environment:
      - MCP_TRANSPORT=streamable-http
      - MCP_LOG_LEVEL=INFO
    stdin_open: true
    tty: true

  mcp-server-http:
    build: .
    environment:
      - MCP_TRANSPORT=streamable-http
      - MCP_HOST=0.0.0.0
      - MCP_PORT=8080
      - MCP_LOG_LEVEL=INFO
    ports:
      - "8080:8080"

  mcp-server-sse:
    build: .
    environment:
      - MCP_TRANSPORT=sse
      - MCP_HOST=0.0.0.0
      - MCP_PORT=8081
      - MCP_LOG_LEVEL=INFO
    ports:
      - "8081:8081"

# /etc/systemd/system/mcp-server.service
[Unit]
Description=MCP Server
After=network.target

[Service]
Type=simple
User=mcp
WorkingDirectory=/opt/mcp-server
Environment=MCP_TRANSPORT=streamable-http
Environment=MCP_HOST=0.0.0.0
Environment=MCP_PORT=8080
Environment=MCP_LOG_LEVEL=INFO
Environment=MCP_ENVIRONMENT=production
ExecStart=/opt/mcp-server/.venv/bin/python -m mcp_server
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

{
  "name": "mcp-server",
  "script": "python",
  "args": ["-m", "mcp_server"],
  "cwd": "/opt/mcp-server",
  "interpreter": "/opt/mcp-server/.venv/bin/python",
  "env": {
    "MCP_TRANSPORT": "streamable-http",
    "MCP_HOST": "0.0.0.0",
    "MCP_PORT": "8080", 
    "MCP_LOG_LEVEL": "INFO",
    "MCP_ENVIRONMENT": "production"
  }
}

apiVersion: apps/v1
kind: Deployment
metadata:
  name: mcp-server
spec:
  replicas: 3
  selector:
    matchLabels:
      app: mcp-server
  template:
    metadata:
      labels:
        app: mcp-server
    spec:
      containers:
      - name: mcp-server
        image: my-mcp-server:latest
        env:
        - name: MCP_TRANSPORT
          value: "streamable-http"
        - name: MCP_HOST
          value: "0.0.0.0"
        - name: MCP_PORT
          value: "8080"
        - name: MCP_ENVIRONMENT
          value: "production"
        ports:
        - containerPort: 8080
---
apiVersion: v1
kind: Service
metadata:
  name: mcp-server-service
spec:
  selector:
    app: mcp-server
  ports:
  - port: 80
    targetPort: 8080
  type: LoadBalancer

# Clone and setup
git clone <repo-url>
cd mcp-server-template
uv venv
source .venv/bin/activate
uv install --group dev

# Set development environment
export MCP_ENVIRONMENT=development
export MCP_LOG_LEVEL=DEBUG

# Format and lint code  
source .venv/bin/activate && uv run ruff check src tests --fix
source .venv/bin/activate && uv run ruff format src tests

# Type checking (mypy not included in current dependencies)
# Add mypy to dev dependencies if type checking is needed

# Run all quality checks
source .venv/bin/activate && uv run pytest && uv run ruff check src tests

# Test default streamable HTTP mode
export MCP_TRANSPORT=streamable-http && source .venv/bin/activate && uv run python -m mcp_server

# Test SSE mode
export MCP_TRANSPORT=sse && export MCP_PORT=8081 && source .venv/bin/activate && uv run python -m mcp_server

# Verify tool registration
source .venv/bin/activate && uv run python -c "
from mcp_server.tools.registry import get_all_tools
print([tool.__class__.__name__ for tool in get_all_tools()])
"

# Test new components
source .venv/bin/activate && uv run python diagnosis_test.py

4. **Docker issues**:

```bash
# Check container logs
docker logs <container-id>

# Interactive debugging
docker run -it --entrypoint /bin/bash my-mcp-server

# Test different transports
docker run -e MCP_TRANSPORT=streamable-http -e MCP_PORT=8080 -p 8080:8080 my-mcp-server

export MCP_LOG_LEVEL=DEBUG
export MCP_ENVIRONMENT=development
source .venv/bin/activate && uv run python -m mcp_server

# Basic functionality test
source .venv/bin/activate && uv run python diagnosis_test.py

# Full verification test  
source .venv/bin/activate && uv run python verification_test.py

# Test specific transport
export MCP_TRANSPORT=streamable-http && source .venv/bin/activate && uv run python verification_test.py

# Automatic transport detection and configuration
await mcp.run_async(
    transport="streamable-http",  # Streamable HTTP server mode
    transport="sse"              # Server-Sent Events mode
)

from fastmcp import tool

@tool
async def validated_function(count: int, name: str) -> dict:
    """FastMCP handles automatic type conversion and validation."""
    return {"count": count, "name": name}

# FastMCP provides comprehensive error handling
try:
    result = await tool.execute(params)
except ValidationError as e:
    logger.error(f"Validation error: {e}")
except Exception as e:
    logger.error(f"Execution error: {e}")

# The template uses lazy imports for optimal startup
def create_server():
    from .server import create_server as _create_server
    return _create_server()