1 files changed, 152 insertions, 0 deletions
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..678e162
--- /dev/null
+++ b/README.md
@@ -0,0 +1,152 @@
+# 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.