Add input validation and update documentation

Security improvements:
- Add validation for employee_id (positive integer)
- Add validation for strings (max length, trimming)
- Add validation for date format (YYYY-MM-DD)
- Add validation for NIF (non-negative integer)
- Replace verbose error messages with generic ones

Documentation:
- Document all MCP tools and parameters
- Add MCP configuration example
- List security features

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

README.md

@@ -8,7 +8,73 @@ sdk_version: 5.43.1
 app_file: app.py
 pinned: false
 license: apache-2.0
-short_description: NP MCP test
+short_description: MCP Server for Employee Management
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# NPTools - Employee Management MCP Server
+
+An MCP (Model Context Protocol) server that provides tools for managing employee records via OutSystems REST API.
+
+## Available Tools
+
+| Tool | Description | Parameters |
+|------|-------------|------------|
+| `get_employees` | Get list of all employees | None |
+| `get_employee_by_id` | Get a specific employee by ID | `employee_id` (required, integer) |
+| `create_employee` | Create a new employee record | `name` (required), `nif`, `date_of_birth`, `address` |
+
+## Tool Details
+
+### get_employees
+Returns a list of all employees with fields: Id, Name, NIF, DateOfBirth, Address, CreatedOn, Phone.
+
+### get_employee_by_id
+Fetches a single employee by their unique identifier.
+
+**Parameters:**
+- `employee_id` (integer, required): The unique identifier of the employee
+
+### create_employee
+Creates a new employee record in the system.
+
+**Parameters:**
+- `name` (string, required): Employee name (max 500 characters)
+- `nif` (integer, optional): Tax identification number
+- `date_of_birth` (string, optional): Date of birth in YYYY-MM-DD format
+- `address` (string, optional): Employee address (max 500 characters)
+
+## MCP Configuration
+
+To use this MCP server with Claude Desktop or other MCP clients, add to your configuration:
+
+```json
+{
+  "mcpServers": {
+    "nptools": {
+      "url": "https://nelsondiasandre-nptools.hf.space/gradio_api/mcp/sse"
+    }
+  }
+}
+```
+
+## Web Interface
+
+The Gradio interface provides tabs for testing each endpoint:
+- **Get All Employees**: Fetch all employee records
+- **Get Employee by ID**: Look up a specific employee
+- **Create Employee**: Add a new employee record
+- **MCP Protocol**: Raw MCP JSON-RPC interface for testing
+
+## Backend API
+
+This MCP server connects to an OutSystems REST API at:
+`https://nelsonandre.outsystemscloud.com/MCPServer/rest/MCP`
+
+## Security Features
+
+- Input validation for all parameters
+- String length limits (500 characters max)
+- Date format validation (YYYY-MM-DD)
+- Positive integer validation for IDs
+- Non-negative validation for NIF
+- Generic error messages (no internal details leaked)

app.py

@@ -1,10 +1,54 @@
 import gradio as gr
 import httpx
 import json
-from typing import Any, Dict, List
-import asyncio
+import re
 
 BASE_URL = "https://nelsonandre.outsystemscloud.com/MCPServer/rest/MCP"
+MAX_STRING_LENGTH = 500
+DATE_PATTERN = re.compile(r"^\d{4}-\d{2}-\d{2}$")
+
+
+def validate_employee_id(employee_id) -> int:
+    """Validate and convert employee ID to a positive integer."""
+    try:
+        eid = int(employee_id)
+        if eid <= 0:
+            raise ValueError("Employee ID must be a positive integer")
+        return eid
+    except (TypeError, ValueError) as e:
+        raise ValueError(f"Invalid employee ID: {e}")
+
+
+def validate_string(value: str, field_name: str, required: bool = False, max_length: int = MAX_STRING_LENGTH) -> str:
+    """Validate and sanitize string input."""
+    if value is None:
+        value = ""
+    value = str(value).strip()
+    if required and not value:
+        raise ValueError(f"{field_name} is required")
+    if len(value) > max_length:
+        raise ValueError(f"{field_name} exceeds maximum length of {max_length}")
+    return value
+
+
+def validate_date(value: str, field_name: str) -> str:
+    """Validate date format (YYYY-MM-DD)."""
+    if not value:
+        return ""
+    if not DATE_PATTERN.match(value):
+        raise ValueError(f"{field_name} must be in YYYY-MM-DD format")
+    return value
+
+
+def validate_nif(value) -> int:
+    """Validate NIF as a non-negative integer."""
+    try:
+        nif = int(value) if value else 0
+        if nif < 0:
+            raise ValueError("NIF cannot be negative")
+        return nif
+    except (TypeError, ValueError):
+        raise ValueError("NIF must be a valid integer")
 
 async def get_employees() -> list[dict]:
     """
@@ -25,9 +69,9 @@ async def get_employees() -> list[dict]:
             response.raise_for_status()
             return response.json()
         except httpx.HTTPStatusError as e:
-            raise Exception(f"HTTP Error {e.response.status_code}: {e.response.text}")
-        except Exception as e:
-            raise Exception(f"Error: {str(e)}")
+            raise Exception(f"Failed to fetch employees (HTTP {e.response.status_code})")
+        except Exception:
+            raise Exception("Failed to connect to employee service")
 
 async def get_employee_by_id(employee_id: int) -> dict:
     """
@@ -46,15 +90,20 @@ async def get_employee_by_id(employee_id: int) -> dict:
         CreatedOn (datetime): Date and time when the employee was created
         Phone (str): Employee's phone number
     """
+    validated_id = validate_employee_id(employee_id)
     async with httpx.AsyncClient() as client:
         try:
-            response = await client.get(f"{BASE_URL}/GetEmployeeBy", params={"EmployeeId": employee_id})
+            response = await client.get(f"{BASE_URL}/GetEmployeeBy", params={"EmployeeId": validated_id})
             response.raise_for_status()
             return response.json()
         except httpx.HTTPStatusError as e:
-            raise Exception(f"HTTP Error {e.response.status_code}: {e.response.text}")
-        except Exception as e:
-            raise Exception(f"Error: {str(e)}")
+            if e.response.status_code == 404:
+                raise Exception("Employee not found")
+            raise Exception(f"Failed to fetch employee (HTTP {e.response.status_code})")
+        except ValueError as e:
+            raise Exception(str(e))
+        except Exception:
+            raise Exception("Failed to connect to employee service")
 
 async def create_employee(name: str, nif: int = 0, date_of_birth: str = "", address: str = "") -> str:
     """
@@ -69,21 +118,29 @@ async def create_employee(name: str, nif: int = 0, date_of_birth: str = "", addr
     Returns:
         str: Result message from the server
     """
+    # Validate all inputs
+    validated_name = validate_string(name, "Name", required=True)
+    validated_nif = validate_nif(nif)
+    validated_dob = validate_date(date_of_birth, "Date of birth")
+    validated_address = validate_string(address, "Address", required=False)
+
     async with httpx.AsyncClient() as client:
         try:
             payload = {
-                "EmployeeName": name,
-                "NIF": nif,
-                "DateOfBirth": date_of_birth,
-                "Address": address
+                "EmployeeName": validated_name,
+                "NIF": validated_nif,
+                "DateOfBirth": validated_dob,
+                "Address": validated_address
             }
             response = await client.post(f"{BASE_URL}/EmployeeCreate", json=payload)
             response.raise_for_status()
             return response.text
         except httpx.HTTPStatusError as e:
-            raise Exception(f"HTTP Error {e.response.status_code}: {e.response.text}")
-        except Exception as e:
-            raise Exception(f"Error: {str(e)}")
+            raise Exception(f"Failed to create employee (HTTP {e.response.status_code})")
+        except ValueError as e:
+            raise Exception(str(e))
+        except Exception:
+            raise Exception("Failed to connect to employee service")
 
 # MCP Protocol handler
 async def handle_mcp_request(request_data: str) -> str:
@@ -179,17 +236,27 @@ async def handle_mcp_request(request_data: str) -> str:
                             "message": "Missing required parameter: employee_id"
                         }
                     })
-                result = await get_employee_by_id(int(employee_id))
-                return json.dumps({
-                    "jsonrpc": "2.0",
-                    "id": request.get("id"),
-                    "result": {
-                        "content": [{
-                            "type": "text",
-                            "text": json.dumps(result, indent=2)
-                        }]
-                    }
-                })
+                try:
+                    result = await get_employee_by_id(employee_id)
+                    return json.dumps({
+                        "jsonrpc": "2.0",
+                        "id": request.get("id"),
+                        "result": {
+                            "content": [{
+                                "type": "text",
+                                "text": json.dumps(result, indent=2)
+                            }]
+                        }
+                    })
+                except Exception as e:
+                    return json.dumps({
+                        "jsonrpc": "2.0",
+                        "id": request.get("id"),
+                        "error": {
+                            "code": -32602,
+                            "message": str(e)
+                        }
+                    })
 
             elif tool_name == "create_employee":
                 name = arguments.get("name")
@@ -202,22 +269,32 @@ async def handle_mcp_request(request_data: str) -> str:
                             "message": "Missing required parameter: name"
                         }
                     })
-                result = await create_employee(
-                    name=name,
-                    nif=arguments.get("nif", 0),
-                    date_of_birth=arguments.get("date_of_birth", ""),
-                    address=arguments.get("address", "")
-                )
-                return json.dumps({
-                    "jsonrpc": "2.0",
-                    "id": request.get("id"),
-                    "result": {
-                        "content": [{
-                            "type": "text",
-                            "text": result
-                        }]
-                    }
-                })
+                try:
+                    result = await create_employee(
+                        name=name,
+                        nif=arguments.get("nif", 0),
+                        date_of_birth=arguments.get("date_of_birth", ""),
+                        address=arguments.get("address", "")
+                    )
+                    return json.dumps({
+                        "jsonrpc": "2.0",
+                        "id": request.get("id"),
+                        "result": {
+                            "content": [{
+                                "type": "text",
+                                "text": result
+                            }]
+                        }
+                    })
+                except Exception as e:
+                    return json.dumps({
+                        "jsonrpc": "2.0",
+                        "id": request.get("id"),
+                        "error": {
+                            "code": -32602,
+                            "message": str(e)
+                        }
+                    })
         
         # Default error response
         return json.dumps({