# 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:**
   ```bash
   make install-dev
   ```

2. **Run the server (http mode on port 8005):**
   ```bash
   make run-http
   ```

3. **Run tests:**
   ```bash
   make test
   ```

### Docker

1. **Build and run:**
   ```bash
   make docker-build
   make docker-run
   ```

2. **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

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:
```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! 🐄**