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
-
Install dependencies:
bash make install-dev -
Run the server (http mode on port 8005):
bash make run-http -
Run tests:
bash make test
Docker
-
Build and run:
bash make docker-build make docker-run -
For HTTP transport:
bash 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:**```python
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:```bash
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:```json
{
"mcpServers": {
"demo-mcp-server": {
"command": "python",
"args": ["-m", "src.mcp"],
"cwd": "/path/to/my-mcp-server"
}
}
}
### Command Line```bash
# 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```bash
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```bash
# 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
- Create a new tool file in
src/mcp/tools/ - Implement the tool using FastMCP patterns
- Register it in
src/mcp/server.py - Add tests in
tests/
Example tool structure:```python
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```bash
docker-compose build
Running
STDIO mode (for MCP clients):```bash
docker-compose up demo-mcp-server
**HTTP mode (for testing):**```bash
docker-compose --profile http up demo-mcp-http
Environment Variables in Docker
Create a .env file or set environment variables in docker-compose.yml:```yaml
environment:
- APP_NAME=My Custom MCP Server
- LOG_LEVEL=DEBUG
## Health Checks
Check server health:```bash
make health
Or directly:bash
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! 🐄
