Demo MCP Server

A minimal FastMCP Python server demonstrating basic MCP (Model Context Protocol) functionality with a simple cowsay tool.

Features

• FastMCP Server: Simple MCP server implementation
• Cowsay Tool: Generate ASCII art of a cow saying custom messages
• Environment Configuration: .env file support with Pydantic settings
• Docker Support: Full Docker and docker-compose setup
• Testing: Basic unit tests with pytest
• KISS Principle: Keep It Simple, focused implementation

Quick Start

Local Development

1. Install dependencies:

   make install-dev
   

2. Run the server (http mode on port 8005):

   make run-http
   

3. Run tests:

   make test
   

Docker

1. Build and run:

   make docker-build
   make docker-run
   

2. For HTTP transport:

   make docker-run-http
   

Project Structure

my-mcp-server/
├── src/
│   ├── config/
│   │   └── settings.py          # Environment configuration
│   └── mcp/
│       ├── __main__.py          # Entry point
│       ├── server.py            # FastMCP server setup
│       └── tools/
│           └── cowsay.py        # Cowsay MCP tool
├── tests/                       # Unit tests
├── .env.example                 # Environment variables template
├── docker-compose.yml           # Docker compose configuration
├── Dockerfile                   # Docker container definition
├── Makefile                     # Common commands
└── pyproject.toml              # Python project configuration

Available Tools

cowsay

Generate ASCII art of a cow saying a message.

Parameters:

• message (str): The message for the cow to say
• cow (str, optional): The type of cow to use (default: "default")

Example:

result = await cowsay("Hello, World!")

Output:

 _______________
< Hello, World! >
 ---------------
        \   ^__^
         \  (oo)\_______
            (__)\       )\/\
                ||----w |
                ||     ||

Configuration

The server uses environment variables for configuration. Copy .env.example to .env and customize:

cp .env.example .env

Available Settings

| Variable | Default | Description | |----------|---------|-------------| | APP_NAME | "Demo MCP Server" | Application name | | LOG_LEVEL | "INFO" | Logging level | | MCP_TRANSPORT | "stdio" | MCP transport method | | MCP_HOST | "127.0.0.1" | Host for HTTP transport | | MCP_PORT | "8000" | Port for HTTP transport | | MAX_MESSAGE_LENGTH | "500" | Maximum cowsay message length |

Usage with MCP Clients

Claude Desktop

Add to your MCP settings:

{
  "mcpServers": {
    "demo-mcp-server": {
      "command": "python",
      "args": ["-m", "src.mcp"],
      "cwd": "/path/to/my-mcp-server"
    }
  }
}

Command Line

# STDIO transport (default)
python -m src.mcp --transport stdio

# HTTP transport
python -m src.mcp --transport http --port 8000

# Help
python -m src.mcp --help

Development

Available Make Commands

make help              # Show all available commands

# Development
make install           # Install dependencies
make install-dev       # Install with dev dependencies
make test             # Run tests
make test-verbose     # Run tests with verbose output

# Running
make run              # Run server locally (STDIO)
make run-http         # Run server locally (HTTP)
make health           # Check server health

# Docker
make docker-build     # Build Docker image
make docker-run       # Run in Docker (STDIO)
make docker-run-http  # Run in Docker (HTTP)
make docker-stop      # Stop containers
make docker-clean     # Clean containers and images

# Cleanup
make clean            # Clean build artifacts

Testing

# Run all tests
make test

# Run with coverage
python -m pytest --cov=src --cov-report=html

# Run specific test
python -m pytest tests/test_cowsay.py -v

Adding New Tools

1. Create a new tool file in src/mcp/tools/
2. Implement the tool using FastMCP patterns
3. Register it in src/mcp/server.py
4. Add tests in tests/

Example tool structure:

from fastmcp.tools import Tool

def create_my_tool() -> Tool:
    async def my_tool(param: str) -> dict:
        # Tool implementation
        return {"success": True, "result": param}
    
    return Tool(
        name="my_tool",
        description="Description of my tool",
        func=my_tool,
    )

Docker

Building

docker-compose build

Running

STDIO mode (for MCP clients):

docker-compose up demo-mcp-server

HTTP mode (for testing):

docker-compose --profile http up demo-mcp-http

Environment Variables in Docker

Create a .env file or set environment variables in docker-compose.yml:

environment:
  - APP_NAME=My Custom MCP Server
  - LOG_LEVEL=DEBUG

Health Checks

Check server health:

make health

Or directly:

python -c "from src.mcp.server import get_server_health; import json; print(json.dumps(get_server_health(), indent=2))"

License

MIT License - feel free to use this as a starting point for your own MCP servers.

Contributing

This is a demo/seed project. Feel free to fork and extend it for your own needs.

Happy MCP Development! 🐄