blob: 259021f9b12a5b151aa9c47708372100dbd2f9f1 (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
|
# MCP Servers Monorepo
This repository is a monorepo that 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.
|
