"""Base schema helpers for Dolibarr MCP tools.
These helpers reduce code duplication when defining tool input schemas.
"""
from typing import Any, Dict, List, Optional
def id_schema(name: str, description: Optional[str] = None) -> Dict[str, Any]:
"""Generate a simple ID-based schema for single-entity operations.
Args:
name: The parameter name (e.g., "user_id", "customer_id")
description: Optional description (defaults to the parameter name)
Returns:
JSON Schema for a single required ID parameter
Example:
>>> id_schema("user_id")
{
"type": "object",
"properties": {"user_id": {"type": "integer", "description": "user_id"}},
"required": ["user_id"],
"additionalProperties": False
}
"""
return {
"type": "object",
"properties": {
name: {
"type": "integer",
"description": description or name
}
},
"required": [name],
"additionalProperties": False
}
def list_schema(
with_status: bool = False,
status_type: str = "string",
with_page: bool = False,
default_limit: int = 100
) -> Dict[str, Any]:
"""Generate a schema for list/pagination operations.
Args:
with_status: Include a status filter parameter
status_type: Type of status parameter ("string" or "integer")
with_page: Include page parameter for pagination
default_limit: Default limit value
Returns:
JSON Schema for list operation parameters
Example:
>>> list_schema(with_status=True, status_type="integer")
{
"type": "object",
"properties": {
"limit": {"type": "integer", "default": 100, "description": "Max results (1-500)"},
"status": {"type": "integer", "description": "Filter by status"}
},
"additionalProperties": False
}
"""
props: Dict[str, Any] = {
"limit": {
"type": "integer",
"default": default_limit,
"description": "Max results (1-500)"
}
}
if with_page:
props["page"] = {
"type": "integer",
"default": 1,
"description": "Page number (1-indexed)"
}
if with_status:
props["status"] = {
"type": status_type,
"description": "Filter by status"
}
return {
"type": "object",
"properties": props,
"additionalProperties": False
}
def search_schema(
query_description: str = "Search query",
default_limit: int = 20
) -> Dict[str, Any]:
"""Generate a schema for search operations.
Args:
query_description: Description for the query parameter
default_limit: Default limit for search results
Returns:
JSON Schema for search operation parameters
Example:
>>> search_schema("Customer name to search")
{
"type": "object",
"properties": {
"query": {"type": "string", "description": "Customer name to search"},
"limit": {"type": "integer", "default": 20, "description": "Max results (1-100)"}
},
"required": ["query"],
"additionalProperties": False
}
"""
return {
"type": "object",
"properties": {
"query": {
"type": "string",
"description": query_description
},
"limit": {
"type": "integer",
"default": default_limit,
"description": "Max results (1-100)"
}
},
"required": ["query"],
"additionalProperties": False
}
def line_schema(entity: str) -> Dict[str, Any]:
"""Generate a schema for adding line items to invoices/proposals/orders.
Args:
entity: Entity type ("invoice", "proposal", or "order")
Returns:
JSON Schema for line item addition
Example:
>>> line_schema("invoice")
{
"type": "object",
"properties": {
"invoice_id": {"type": "integer", "description": "Invoice ID"},
"desc": {"type": "string", "description": "Line description"},
"qty": {"type": "number", "description": "Quantity"},
"subprice": {"type": "number", "description": "Unit price (excl. tax)"},
"product_id": {"type": "integer", "description": "Product ID (optional)"},
"product_type": {"type": "integer", "default": 0, "description": "0=product, 1=service"},
"tva_tx": {"type": "number", "description": "VAT rate (e.g., 19.0)"}
},
"required": ["invoice_id", "desc", "qty", "subprice"],
"additionalProperties": False
}
"""
return {
"type": "object",
"properties": {
f"{entity}_id": {
"type": "integer",
"description": f"{entity.capitalize()} ID"
},
"desc": {
"type": "string",
"description": "Line description"
},
"qty": {
"type": "number",
"description": "Quantity"
},
"subprice": {
"type": "number",
"description": "Unit price (excl. tax)"
},
"product_id": {
"type": "integer",
"description": "Product ID (optional)"
},
"product_type": {
"type": "integer",
"default": 0,
"description": "0=product, 1=service"
},
"tva_tx": {
"type": "number",
"description": "VAT rate (e.g., 19.0)"
}
},
"required": [f"{entity}_id", "desc", "qty", "subprice"],
"additionalProperties": False
}
def empty_schema() -> Dict[str, Any]:
"""Generate an empty schema for parameter-less operations.
Returns:
JSON Schema with no parameters
"""
return {
"type": "object",
"properties": {},
"additionalProperties": False
}
def update_line_schema(entity: str) -> Dict[str, Any]:
"""Generate a schema for updating line items.
Args:
entity: Entity type ("invoice" or "proposal")
Returns:
JSON Schema for line item update
"""
return {
"type": "object",
"properties": {
f"{entity}_id": {
"type": "integer",
"description": f"{entity.capitalize()} ID"
},
"line_id": {
"type": "integer",
"description": "Line ID to update"
},
"desc": {
"type": "string",
"description": "New line description"
},
"qty": {
"type": "number",
"description": "New quantity"
},
"subprice": {
"type": "number",
"description": "New unit price"
},
"tva_tx": {
"type": "number",
"description": "New VAT rate"
}
},
"required": [f"{entity}_id", "line_id"],
"additionalProperties": False
}
def delete_line_schema(entity: str) -> Dict[str, Any]:
"""Generate a schema for deleting line items.
Args:
entity: Entity type ("invoice" or "proposal")
Returns:
JSON Schema for line item deletion
"""
return {
"type": "object",
"properties": {
f"{entity}_id": {
"type": "integer",
"description": f"{entity.capitalize()} ID"
},
"line_id": {
"type": "integer",
"description": "Line ID to delete"
}
},
"required": [f"{entity}_id", "line_id"],
"additionalProperties": False
}
