# MCP Servers Monorepo

This repository contains a collection of Model Context Protocol (MCP) servers that can be used to extend LLM agent capabilities.

## Project Structure

```
dawids-mcp-servers/
├── servers/                 # Individual MCP servers
│   ├── hello_world/         # Example server
│   │   ├── src/             # Server source code
│   │   ├── tests/           # Server tests
│   │   ├── Dockerfile       # Server container definition
│   │   └── pyproject.toml   # Server package configuration
│   └── ...                  # Other servers
└── .woodpecker.yml          # CI/CD configuration
```

## Coding Rules for LLM Agent

When implementing new servers or extending existing ones, follow these guidelines:

### Python Package Structure

- Each server is a separate Python package
- Use Python language with uv package manager
- Follow PEP 8 style guidelines
- Use type hints for all functions and methods
- Document all public APIs with docstrings
- Run all commands in uv context

### Code Quality

- Use ruff for linting
- Maintain at least 80% test coverage
- Write unit, integration, and end-to-end tests
- Use pytest for testing

### Server Implementation

- Each server must support two transport methods:
  1. stdio transport for local development and testing
  2. Remote endpoint (HTTP) for production use
- Transport method should be selectable via input parameter
- Follow the MCP protocol specification

### Containerization

- Each server should have its own Dockerfile
- Follow Docker best practices:
  - Use multi-stage builds
  - Run as non-root user
  - Include health checks
  - Minimize image size
- Lint Dockerfiles with hadolint

### Dependencies

- Clearly specify dependencies in pyproject.toml
- Pin dependency versions for reproducibility
- Use virtual environments for development

## Creating a New Server

Use servers/hello-world as a template to create a new server. Copy directory to servers/server_name and implement changes.

## Testing

Run tests for a specific server:

```bash
cd servers/server_name
uv run pytest
```

Run tests with coverage:

```bash
cd servers/server_name
uv run pytest --cov=server_name
```

## Building and Running

Build a server Docker image:

```bash
cd servers/server_name
docker build -t server_name .
```

Run a server with stdio transport:

```bash
cd servers/server_name
uv run server_name --transport stdio
```

Run a server with HTTP transport:

```bash
cd servers/server_name
uv run server_name --transport remote --host 0.0.0.0 --port 8080
```

Run a server in Docker:

```bash
docker run -p 8080:8080 server_name
```

## Development Best Practices

### Error Handling

- Log errors with context information
- Return meaningful error messages to clients

### Security

- Don't include sensitive information in logs or responses
- Validate all input data
- Use HTTPS for remote transport in production
- Follow the principle of least privilege

### Performance

- Optimize resource-intensive operations
- Use async/await for I/O-bound operations
- Implement proper caching strategies
- Monitor and profile server performance

### Documentation

- Document the purpose and capabilities of each server
- Include examples of how to use the server's tools and resources
- Document the API schema for each tool and resource
- Keep documentation up-to-date with code changes

## Contributing

When contributing to this repository, please follow these steps:

1. Create a new branch for your feature or bugfix
2. Implement your changes following the coding rules
3. Write tests for your changes
4. Update documentation as needed
5. Submit a pull request

## License

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