Demo MCP Server¶

A simple demonstration MCP server that provides greeting tools using FastMCP and HTTP transport by default.

Overview¶

This demo server showcases the MCP Platform architecture with: - FastMCP integration for tool decorators and HTTP transport - HTTP-first approach with stdio fallback - Docker deployment with networking support - Modular code structure following best practices - Comprehensive configuration with environment variable mapping

Quick Start¶

Local Development¶

# Install dependencies
pip install -r requirements.txt

# Run with defaults (HTTP on port 7071)
python server.py

# Run with custom configuration
python server.py --hello-from "Custom Server" --log-level debug

# Run with stdio transport (for testing)
python server.py --transport stdio

Docker Deployment¶

# Build the image
docker build -t dataeverything/mcp-demo:latest .

# Run with defaults
docker run -p 7071:7071 dataeverything/mcp-demo:latest

# Run with custom configuration
docker run -p 7071:7071 \
  -e MCP_HELLO_FROM="Docker Server" \
  -e MCP_LOG_LEVEL=debug \
  dataeverything/mcp-demo:latest

# Join MCP Platform network
docker network create mcp-platform
docker run --network mcp-platform --name demo \
  -p 7071:7071 dataeverything/mcp-demo:latest

Using MCP Template CLI¶

# Deploy using the CLI
mcp_platform deploy demo

# Deploy with custom configuration
mcp_platform deploy demo --config hello_from="CLI Server"

# Show configuration options
mcpp config demo

# List available tools
mcpp> tools demo

# Get integration examples
mcpp connect demo --llm claude

Usage & API Reference¶

For comprehensive usage examples, tool documentation, and integration guides:

View Complete Usage Guide

The usage guide includes: - Available Tools - Complete list of tools with parameters and examples - Integration Examples - Python, JavaScript, and CLI usage - HTTP API - REST endpoint documentation - Configuration - Setup and deployment options - Best Practices - Tips for optimal usage

Usage & API Reference¶

For comprehensive usage examples, tool documentation, and integration guides:

View Complete Usage Guide

The usage guide includes: - Available Tools - Complete list of tools with parameters and examples - Integration Examples - Python, JavaScript, and CLI usage - HTTP API - REST endpoint documentation - Configuration - Setup and deployment options - Best Practices - Tips for optimal usage

Configuration¶

Environment Variables¶

Variable	Description	Default
`MCP_HELLO_FROM`	Name or message to include in greetings	"MCP Platform"
`MCP_LOG_LEVEL`	Logging level (debug, info, warning, error)	"info"

Usage & API Reference¶

For comprehensive usage examples, tool documentation, and integration guides:

View Complete Usage Guide

The usage guide includes: - Available Tools - Complete list of tools with parameters and examples - Integration Examples - Python, JavaScript, and CLI usage - HTTP API - REST endpoint documentation - Configuration - Setup and deployment options - Best Practices - Tips for optimal usage

Usage & API Reference¶

For comprehensive usage examples, tool documentation, and integration guides:

View Complete Usage Guide

The usage guide includes: - Available Tools - Complete list of tools with parameters and examples - Integration Examples - Python, JavaScript, and CLI usage - HTTP API - REST endpoint documentation - Configuration - Setup and deployment options - Best Practices - Tips for optimal usage

Configuration Options¶

# Direct configuration (for config_schema properties)
--config hello_from="Custom Server"
--config log_level=debug

# Environment variables
--env MCP_HELLO_FROM="Custom Server"
--env MCP_LOG_LEVEL=debug

# Double-underscore notation (for nested configs)
--config demo__hello_from="Custom Server"
--config demo__log_level=debug

Template Data Overrides¶

The demo template supports template data overrides using the --override argument with double underscore notation:

# Modify template metadata
mcp_platform deploy demo \
  --override "metadata__version=2.0.0" \
  --override "metadata__author=Your Name"

# Modify tool configurations
mcp_platform deploy demo \
  --override "tools__0__enabled=false" \
  --override "tools__1__description=Custom echo tool"

# Add custom fields to template
mcp_platform deploy demo \
  --override "custom_field=custom_value" \
  --override "config__debug_mode=true"

# Complex nested structures with automatic type conversion
mcp_platform deploy demo \
  --override "config__features__advanced=true" \
  --override "config__features__timeout=30.5" \
  --override "servers__0__config__host=localhost"

# Combined config and overrides
mcp_platform deploy demo \
  --config hello_from="Custom Server" \
  --override "metadata__version=1.5.0" \
  --override "tools__0__custom_property=value"

Override vs Config Usage:

Use `--config` for:	Use `--override` for:
Server configuration properties	Template metadata changes
Environment variable mappings	Tool modifications
Settings from `config_schema`	Custom field additions
Runtime behavior control	Template structure changes

Type Conversion: Overrides automatically convert values: - "true"/"false" → boolean - "123" → integer - "45.67" → float - '["a","b"]' → JSON array - '{"key":"value"}' → JSON object

Testing Override Functionality:

# Use the demonstrate_overrides tool to see both patterns
python -c "
from templates.demo.server import demonstrate_overrides
print(demonstrate_overrides())
"

Usage & API Reference¶

For comprehensive usage examples, tool documentation, and integration guides:

View Complete Usage Guide

The usage guide includes: - Available Tools - Complete list of tools with parameters and examples - Integration Examples - Python, JavaScript, and CLI usage - HTTP API - REST endpoint documentation - Configuration - Setup and deployment options - Best Practices - Tips for optimal usage

Usage & API Reference¶

For comprehensive usage examples, tool documentation, and integration guides:

View Complete Usage Guide

The usage guide includes: - Available Tools - Complete list of tools with parameters and examples - Integration Examples - Python, JavaScript, and CLI usage - HTTP API - REST endpoint documentation - Configuration - Setup and deployment options - Best Practices - Tips for optimal usage

Configuration Files¶

JSON Configuration (demo-config.json):

{
  "hello_from": "Custom Server",
  "log_level": "debug"
}

YAML Configuration (demo-config.yml):

hello_from: "Custom Server"
log_level: debug

1. say_hello¶

Generate a personalized greeting message.

Parameters: - name (optional): Name of the person to greet

Examples:

# Without name
client.call("say_hello")
# Returns: "Hello! Greetings from MCP Platform!"

# With name
client.call("say_hello", name="Alice")
# Returns: "Hello Alice! Greetings from MCP Platform!"

2. get_server_info¶

Get comprehensive information about the demo server.

Parameters: None

Returns: JSON string with server metadata, configuration, and available tools.

3. echo_message¶

Echo back a message with server identification.

Parameters: - message (required): Message to echo back

Example:

client.call("echo_message", message="Hello World")
# Returns: "[MCP Platform] Echo: Hello World"

¶

Usage & API Reference¶

For comprehensive usage examples, tool documentation, and integration guides:

View Complete Usage Guide

The usage guide includes: - Available Tools - Complete list of tools with parameters and examples - Integration Examples - Python, JavaScript, and CLI usage - HTTP API - REST endpoint documentation - Configuration - Setup and deployment options - Best Practices - Tips for optimal usage

Configuration Options¶

Property	Type	Environment Variable	Default	Description
`hello_from`	string	`MCP_HELLO_FROM`	`MCP Platform`	Name or message to include in greetings
`log_level`	string	`MCP_LOG_LEVEL`	`info`	Logging level for the server
`auth_mode`	string	`MCP_AUTH_MODE`	`none`	Choose authentication method (demo purposes only)
`auth_token`	string	`MCP_AUTH_TOKEN`	``	API token for authentication (required when auth_mode is 'token')
`auth_username`	string	`MCP_AUTH_USERNAME`	``	Username for basic authentication
`auth_password`	string	`MCP_AUTH_PASSWORD`	``	Password for basic authentication
`allowed_dirs`	string	`MCP_ALLOWED_DIRS`	`/tmp`	Directories that the server can access for file operations. Only for demonstration purposes.

Development¶

Project Structure¶

templates/demo/
├── __init__.py          # Package initialization
├── config.py            # Configuration management
├── server.py            # Main server implementation
├── tools.py             # Tool definitions
├── requirements.txt     # Python dependencies
├── Dockerfile           # Container configuration
├── template.json        # Template metadata
├── README.md            # This file
└── tests/               # Test suite
    ├── test_server.py   # Server tests
    ├── test_tools.py    # Tool tests
    └── test_config.py   # Configuration tests

Running Tests¶

# Install test dependencies
pip install pytest pytest-asyncio

# Run all tests
pytest tests/

# Run specific test file
pytest tests/test_tools.py -v

# Run with coverage
pytest tests/ --cov=. --cov-report=html

Code Style¶

This project follows: - PEP 8 style guidelines - Type hints for all functions - Docstrings for all public functions - Logging instead of print statements

Architecture¶

The demo server follows the MCP Platform architecture:

BaseMCPServer: Base class providing common functionality
DemoServerConfig: Configuration management with environment mapping
Tools Module: FastMCP tool definitions with decorators
Server Module: Main server implementation and CLI

This modular design ensures consistency across templates and makes the code: - Testable: Each module can be tested independently - Maintainable: Clear separation of concerns - Extensible: Easy to add new tools and configuration options - Reusable: Base classes can be used by other templates

Troubleshooting¶

Common Issues¶

Import Error: FastMCP not found
```
pip install fastmcp>=2.10.0
```

Port already in use

# Use a different port
python server.py --port 7072

Docker network issues

# Create the network first
docker network create mcp-platform

Debugging¶

Enable debug logging to see detailed information:

# Local development
python server.py --log-level debug

# Docker
docker run -e MCP_LOG_LEVEL=debug dataeverything/mcp-demo:latest

# CLI deployment
mcp_platform deploy demo --config log_level=debug

Contributing¶

Fork the repository
Create a feature branch
Make your changes following the code style
Add tests for new functionality
Update documentation
Submit a pull request

License¶

This project is licensed under the MIT License - see the LICENSE file for details.