Skip to content

Commit f825889

Browse files
cvicenscvicens
committed
additions
1 parent e5fbfff commit f825889

File tree

2 files changed

+330
-0
lines changed

2 files changed

+330
-0
lines changed

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2024 Alpha Hack Group
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md‎

Lines changed: 309 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,309 @@
1+
# BON Calculadora MCP Server
2+
3+
> **Example Model Context Protocol (MCP) Server demonstrating leave assistance evaluation based on fictional Navarra 2025 regulations**
4+
5+
[![CI Pipeline](https://github.com/alpha-hack-program/bon-calculadora-mcp-rs/actions/workflows/ci.yml/badge.svg)](https://github.com/alpha-hack-program/bon-calculadora-mcp-rs/actions/workflows/ci.yml)
6+
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
7+
[![Rust](https://img.shields.io/badge/rust-%23000000.svg?style=flat&logo=rust&logoColor=white)](https://www.rust-lang.org/)
8+
9+
An example Model Context Protocol (MCP) server developed in Rust that demonstrates how to evaluate complex business rules using the ZEN Engine decision engine. This project serves as a reference implementation for building MCP servers with rule-based decision systems.
10+
11+
## ⚠️ **DISCLAIMER**
12+
13+
**This is a demonstration/example project only.** The regulations, amounts, and evaluation logic implemented here are fictional and created solely for educational and demonstration purposes. This software:
14+
15+
- **Should NOT be used for actual legal or administrative decisions**
16+
- **Does NOT represent real Navarra government regulations**
17+
- **Is NOT affiliated with any official government entity**
18+
- **Serves as a technical example of MCP server implementation**
19+
20+
For real legal advice or official information about leave assistance, please consult official government sources and qualified legal professionals.
21+
22+
## 🎯 Features
23+
24+
- **5 Example Evaluation Scenarios**: Demonstrates implementation of complex rule sets (A-E)
25+
- **Decision Engine Integration**: Shows how to use ZEN Engine for rule-based evaluation
26+
- **Multiple Transport Protocols**: Examples of STDIO, SSE, and HTTP streamable implementations
27+
- **Robust Input Validation**: Demonstrates JSON schema validation with detailed error handling
28+
- **Production-Ready Containerization**: Example Docker/Podman setup for deployment
29+
- **Claude Desktop Integration**: Example DXT packaging for MCP integration
30+
31+
## 📋 Example Assistance Scenarios (Fictional)
32+
33+
| Scenario | Description | Example Monthly Amount |
34+
|----------|-------------|------------------------|
35+
| **A** | Care for first-degree relative (illness/accident) | 725€ |
36+
| **B** | Third child or more with newborn | 500€ |
37+
| **C** | Adoption or foster care | 500€ |
38+
| **D** | Multiple birth, adoption, or foster care | 500€ |
39+
| **E** | Single-parent families | 500€ |
40+
41+
> **Note**: These scenarios and amounts are completely fictional and used only for demonstration purposes.
42+
43+
## 🚀 Quick Start
44+
45+
### Prerequisites
46+
47+
- Rust 1.70+ ([Install Rust](https://rustup.rs/))
48+
- Cargo (included with Rust)
49+
50+
### Installation
51+
52+
```bash
53+
# Clone the repository
54+
git clone https://github.com/alpha-hack-program/bon-calculadora-mcp-rs.git
55+
cd bon-calculadora-mcp-rs
56+
57+
# Build all servers
58+
make build-all
59+
60+
# Or build individually
61+
make build-sse # SSE Server
62+
make build-mcp # MCP HTTP Server
63+
make build-stdio # STDIO Server for Claude
64+
```
65+
66+
### Running
67+
68+
```bash
69+
# SSE Server (recommended for development)
70+
make test-sse
71+
72+
# MCP HTTP Server
73+
make test-mcp
74+
75+
# Or directly
76+
RUST_LOG=debug ./target/release/sse_server
77+
```
78+
79+
## 🔧 Configuration
80+
81+
### Environment Variables
82+
83+
```bash
84+
# Server configuration
85+
HOST=127.0.0.1 # Bind address (0.0.0.0 for containers)
86+
PORT=8001 # Server port
87+
RUST_LOG=info # Logging level (debug, info, warn, error)
88+
89+
# Or use BIND_ADDRESS directly
90+
BIND_ADDRESS=127.0.0.1:8001
91+
```
92+
93+
### Example Usage
94+
95+
```json
96+
{
97+
"input": {
98+
"parentesco": "madre",
99+
"situacion": "enfermedad",
100+
"familia_monoparental": false,
101+
"numero_hijos": 2
102+
}
103+
}
104+
```
105+
106+
**Example Response:**
107+
```json
108+
{
109+
"output": {
110+
"supuesto": "A",
111+
"descripcion": "Care for first-degree relative (illness or accident)",
112+
"importe_mensual": 725,
113+
"tiene_derecho_potencial": true,
114+
"requisitos_adicionales": "The person must have been hospitalized..."
115+
}
116+
}
117+
```
118+
119+
> **Important**: This is example data for demonstration purposes only.
120+
121+
## 🐳 Containerization
122+
123+
### Build and Run
124+
125+
This requires `podman` or `docker`. Adapt `.env` to your needs.
126+
127+
```bash
128+
# Build container image
129+
./image.sh build
130+
131+
# Run locally
132+
./image.sh run
133+
134+
# Run from remote registry
135+
./image.sh push
136+
./image.sh run-remote
137+
```
138+
139+
### Environment Variables for Containers
140+
141+
```bash
142+
# Production configuration
143+
docker run -p 8001:8001 \
144+
-e HOST=0.0.0.0 \
145+
-e PORT=8001 \
146+
-e RUST_LOG=info \
147+
quay.io/atarazana/bon-calculadora-mcp-server:latest
148+
```
149+
150+
## 📦 Claude Desktop Integration
151+
152+
### Packaging
153+
154+
```bash
155+
# Create DXT package for Claude Desktop
156+
make pack
157+
```
158+
159+
### Example Claude Configuration
160+
161+
Drag and drop the `DXT` file into the `Settings->Extensions` dropping area.
162+
163+
> **Note**: This demonstrates MCP integration patterns and is not intended for production use with real data.
164+
165+
## 🧪 Testing
166+
167+
```bash
168+
# Run all tests
169+
make test
170+
```
171+
172+
### Manual Testing Examples
173+
174+
Run the server: `make test-sse` or `./image.sh run`.
175+
176+
> This requires NodeJS 19+.
177+
178+
In another terminal.
179+
180+
```bash
181+
make inspector
182+
```
183+
184+
Then connect your browser to the suggest url given by the MCP inspector. Once there connect to `http://localhost:${PORT}/sse`
185+
186+
> `PORT` is set in `.env`
187+
188+
Connect and list tools, select the tool and use this JSON.
189+
190+
```json
191+
{
192+
"parentesco": "hijo",
193+
"situacion": "parto",
194+
"familia_monoparental": true
195+
}
196+
```
197+
198+
## 🛠️ Development
199+
200+
### Available Commands
201+
202+
```bash
203+
make help # Show help
204+
make build-all # Build all servers
205+
make clean # Clean artifacts
206+
make fmt # Format code
207+
make lint # Run clippy
208+
make audit # Security audit
209+
make dev # Development server with auto-reload
210+
```
211+
212+
### Project Structure
213+
214+
```
215+
├── src/
216+
│ ├── common/
217+
│ │ ├── calculadora.rs # MCP logic and decision engine
218+
│ │ └── mod.rs
219+
│ ├── sse_server.rs # SSE Server
220+
│ ├── mcp_server.rs # MCP HTTP Server
221+
│ └── stdio_server.rs # STDIO Server
222+
├── dxt/
223+
│ └── manifest.json # Claude Desktop manifest
224+
├── Containerfile # Container definition
225+
├── Makefile # Build commands
226+
└── container.sh # Container management script
227+
```
228+
229+
### Debug and Monitoring
230+
231+
```bash
232+
# Debug proxy
233+
make proxy # Start mitmproxy on port 8888
234+
235+
# MCP Inspector
236+
make inspector # Start MCP Inspector
237+
238+
# Supergateway for SSE
239+
make sgw-sse # STDIO -> SSE wrapping
240+
241+
# Supergateway for MCP
242+
make sgw-mcp # STDIO -> MCP HTTP wrapping
243+
```
244+
245+
## 📚 API Reference
246+
247+
### Main Endpoint
248+
249+
**POST** `/message` - Example endpoint for rule evaluation
250+
251+
### Example Input Parameters
252+
253+
| Field | Type | Required | Description |
254+
|-------|------|----------|-------------|
255+
| `parentesco` | string | ✅ | Family relationship (padre, madre, hijo, hija, conyuge, pareja, esposo, esposa, mujer, marido) |
256+
| `situacion` | string | ✅ | Care reason (parto, adopcion, acogimiento, enfermedad, accidente, etc.) |
257+
| `familia_monoparental` | boolean | ✅ | Is it a single-parent family? |
258+
| `numero_hijos` | number | ❌ | Number of children (optional, required for Scenario B) |
259+
260+
### Response
261+
262+
| Field | Type | Description |
263+
|-------|------|-------------|
264+
| `supuesto` | string | Applicable scenario letter (A-E) |
265+
| `descripcion` | string | Scenario description |
266+
| `importe_mensual` | number | Monthly amount in euros |
267+
| `tiene_derecho_potencial` | boolean | Meets basic requirements? |
268+
| `requisitos_adicionales` | string | Additional specific requirements |
269+
| `errores` | array | List of validation errors |
270+
| `advertencias` | array | Warnings and additional information |
271+
272+
## 🔒 Security
273+
274+
- **Input validation**: Strict JSON schemas
275+
- **Non-root user**: Containers run as user `1001`
276+
- **Security audit**: `cargo audit` in CI/CD
277+
- **Minimal image**: Based on UBI 9 minimal
278+
279+
## 🤝 Contributing
280+
281+
1. Fork the project
282+
2. Create feature branch (`git checkout -b feature/new-feature`)
283+
3. Commit changes (`git commit -am 'Add new feature'`)
284+
4. Push to branch (`git push origin feature/new-feature`)
285+
5. Create Pull Request
286+
287+
### Guidelines
288+
289+
- Follow code style with `cargo fmt`
290+
- Pass linting with `cargo clippy`
291+
- Add tests for new functionality
292+
- Update documentation as needed
293+
294+
## 📄 License
295+
296+
This project is licensed under the MIT License - see [LICENSE](LICENSE) for details.
297+
298+
## 🙋 Support
299+
300+
- **Issues**: [GitHub Issues](https://github.com/alpha-hack-program/bon-calculadora-mcp-rs/issues)
301+
- **Documentation**: [Project Wiki](https://github.com/alpha-hack-program/bon-calculadora-mcp-rs/wiki)
302+
303+
## 🏷️ Tags
304+
305+
`mcp` `model-context-protocol` `rust` `calculator` `navarra` `excedencia` `zen-engine` `claude` `decision-engine`
306+
307+
---
308+
309+
**Developed with ❤️ by [Alpha Hack Group](https://github.com/alpha-hack-program)**

0 commit comments

Comments
 (0)