blob: 14f7c0c0d9dee2938283cbb69f1c7228a0bc3571 (
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
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
|
# 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.
## Repository
This repository is hosted at: https://codeberg.org/knightdave/dawids-mcp-servers.git
## Getting Started
```bash
# Clone the repository
git clone https://codeberg.org/knightdave/dawids-mcp-servers.git
cd dawids-mcp-servers
```
## 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 .
```
### Using MCP Servers
To use any of the MCP servers in this repository, you can run them using `uv` from the repository root:
```bash
# Example: Run GitLab glab server
⚠️ **DEPRECATION NOTICE:** The `gitlab_glab` server is deprecated. Use `gitlab_python` instead:
# Example: Run GitLab Python server (recommended)
uv --directory /path-to-repo/dawids-mcp-servers/servers/gitlab_python run mcp-gitlab-python --transport stdio
# (Legacy) Run GitLab glab server
uv --directory /path-to-repo/dawids-mcp-servers/servers/gitlab_glab run mcp-gitlab-glab --transport stdio
# Example: Run hello world server
uv --directory /path-to-repo/dawids-mcp-servers/servers/hello_world run mcp-hello-world --transport stdio
```
Replace `/path-to-repo` with the actual path to where you cloned this repository.
### Repository
This repository is hosted at: https://codeberg.org/knightdave/dawids-mcp-servers.git
### Alternative: Running from server directory
You can also run servers by navigating to their directory first:
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.
|
