"""Definition des outils MCP (operations d'ecriture).""" from __future__ import annotations from typing import Annotated, Any from pydantic import Field from mcp.types import ToolAnnotations from ..services.client_rest import ClientRest, HTTPMethod _WRITE_ONLY = ToolAnnotations(readOnlyHint=False, destructiveHint=False) _WRITE_DESTRUCTIVE = ToolAnnotations(readOnlyHint=False, destructiveHint=True) _WRITE_IDEMPOTENT = ToolAnnotations( readOnlyHint=False, destructiveHint=True, idempotentHint=True ) # --- createResource / updateResource --- Pagetitle = Annotated[str, Field(description="page title of the resource")] PagetitleOpt = Annotated[str | None, Field(default=None, description="page title of the resource")] Alias = Annotated[str | None, Field(default=None, description="alias that will be used in the URL (default: pagetitle)")] Cacheable = Annotated[bool | None, Field(default=None, description="tells if the resource is cacheable")] Content = Annotated[str | None, Field(default=None, description="content of the resource")] ContextKey = Annotated[str | None, Field(default=None, description="context of the resource (default: web)")] Deleted = Annotated[bool | None, Field(default=None, description="tells if the resource is deleted or not")] Description = Annotated[str | None, Field(default=None, description="description of the resource")] Hidemenu = Annotated[bool | None, Field(default=None, description="tells if the resource should be hidden from menu display")] Introtext = Annotated[str | None, Field(default=None, description="introduction of the resource")] ResourceIdDuplicate = Annotated[int | None, Field(default=None, description="a resource id to duplicate")] ResourceId = Annotated[int, Field(description="a resource id to modify")] ResourceIdDelete = Annotated[int, Field(description="resource id to delete")] Isfolder = Annotated[bool | None, Field(default=None, description="tells if the resource is to be considered as a folder of resources")] LinkAttributes = Annotated[str | None, Field(default=None, description="link attributes that may be used in menu or links")] Longtitle = Annotated[str | None, Field(default=None, description="long title of the resource")] Menuindex = Annotated[int | None, Field(default=None, description="order index of the resource in a menu")] Menutitle = Annotated[str | None, Field(default=None, description="title of the resource if displayed in a menu tree")] PagetitleUnique = Annotated[ str | None, Field(default=None, description="if set, modify pagetitle to get a unique pagetitle and alias ('1'/'uniqueid' adds uniqid, 'date' adds timestamp; default: 0)")] Parent = Annotated[int | None, Field(default=None, description="parent of the resource (default: 0, root)")] Published = Annotated[bool | None, Field(default=None, description="tells if the resource is published")] PubDate = Annotated[str | None, Field(default=None, description="date in the future that the resource should be published")] Searchable = Annotated[bool | None, Field(default=None, description="tells if the resource may be found in a search process")] TemplateId = Annotated[int | None, Field(default=None, description="resource id of the template (default: default_template setting, e.g. 12)")] UnpubDate = Annotated[str | None, Field(default=None, description="date when the resource should be unpublished")] TemplateVars = Annotated[dict[str, Any] | list[Any] | str | None, Field(default=None, description="json list of template variables content")] ResourceGroups = Annotated[ dict[str, Any] | list[Any] | str | None, Field(default=None, description="comma-separated list of resource group ids, or JSON '[{\"id\":\"\",\"access\":\"<0|1>\"}]'") ] ResourceGroupsUpdate = Annotated[ dict[str, Any] | list[Any] | str | None, Field(default=None, description="resource groups to add; to remove a group send JSON with access=0") ] MandatoryParents = Annotated[ int | str | list[int] | None, Field(default=None, description="comma-separated list of resource ids giving the authorized parents") ] ContentType = Annotated[str | None, Field(default=None, description="mime type of the resource content (default: text/html)")] Syncsite = Annotated[bool | None, Field(default=None, description="if set, it will refresh the resource cache (default: 0)")] MandatoryParent = Annotated[ int | None, Field(default=None, description="set the mandatory parent of the id to verify the resource id is appropriate") ] # --- createTemplate / updateTemplate --- TemplateName = Annotated[str, Field(description="name of the template")] TemplateNameOpt = Annotated[str | None, Field(default=None, description="name of the template")] TemplateIdMandatory = Annotated[int, Field(description="id of the template")] TemplateDescription = Annotated[str | None, Field(default=None, description="description of the template")] Category = Annotated[str | None, Field(default=None, description="category the element belongs in")] IsStatic = Annotated[ bool | None, Field(default=None, description="if true, the element source is stored in an external file (default: false)") ] StaticFile = Annotated[ str | None, Field(default=None, description="if isStatic true, path of the external file where the element source is stored") ] TemplateContent = Annotated[str | None, Field(default=None, description="template code (HTML)")] LockTemplate = Annotated[ bool | None, Field(default=None, description="lock template for editing; requires edit_locked attribute (default: false)") ] TemplateVarsAccess = Annotated[ dict[str, Any] | list[Any] | str | None, Field(default=None, description="JSON list that indicates the access of template vars (default: {})") ] # --- createTv / updateTv --- TvName = Annotated[str, Field(description="name of the template variable")] TvNameOpt = Annotated[str | None, Field(default=None, description="name of the TV")] TvId = Annotated[int, Field(description="id of the TV")] TvDescription = Annotated[str | None, Field(default=None, description="description of the template variable")] TvCaption = Annotated[str | None, Field(default=None, description="text displayed beside the TV when editing it in a Resource")] TvCategory = Annotated[str | None, Field(default=None, description="category the TV belongs in")] TvType = Annotated[str | None, Field(default=None, description="the type of TV")] TvElements = Annotated[ str | None, Field(default=None, description="list of options for TV; only use if the type of TV is listbox"), ] TvDefaultText = Annotated[ str | None, Field(default=None, description="default option for TV; only use if the type of TV is listbox"), ] TvInputPropeties = Annotated[ str | None, Field(default=None, description="JSON list of the input properties of the TV") ] TvTemplates = Annotated[ dict[str, Any] | list[Any] | str | None, Field(default=None, description="JSON list that indicates the access of templates (default: {})") ] # --- createCategory / updateCategory --- CategoryName = Annotated[str, Field(description="name of the category")] CategoryNameOpt = Annotated[str | None, Field(default=None, description="name of the category")] CategoryId = Annotated[int, Field(description="id of the category")] CategoryParent = Annotated[int | None, Field(default=None, description="parent id of the category (default: 0)")] def _omit_none(**kwargs: Any) -> dict[str, Any]: return {key: value for key, value in kwargs.items() if value is not None} def register_tools(mcp_server: Any, client_rest: ClientRest) -> None: """Enregistre les outils d'ecriture du serveur MCP.""" @mcp_server.tool( description="Creer une ressource MODX", annotations=_WRITE_ONLY, ) def createResource( pagetitle: Pagetitle, alias: Alias = None, cacheable: Cacheable = None, content: Content = None, context_key: ContextKey = None, deleted: Deleted = None, description: Description = None, hidemenu: Hidemenu = None, introtext: Introtext = None, id: ResourceIdDuplicate = None, isfolder: Isfolder = None, link_attributes: LinkAttributes = None, longtitle: Longtitle = None, menuindex: Menuindex = None, menutitle: Menutitle = None, pagetitleUnique: PagetitleUnique = None, parent: Parent = None, published: Published = None, pub_date: PubDate = None, searchable: Searchable = None, template: TemplateId = None, unpub_date: UnpubDate = None, templateVars: TemplateVars = None, resourceGroups: ResourceGroups = None, mandatoryParents: MandatoryParents = None, content_type: ContentType = None, syncsite: Syncsite = None, ) -> dict[str, Any]: return client_rest.execute( method=HTTPMethod.POST, endpoint="/rest/tools/resource", json=_omit_none( pagetitle=pagetitle, alias=alias, cacheable=cacheable, content=content, context_key=context_key, deleted=deleted, description=description, hidemenu=hidemenu, introtext=introtext, id=id, isfolder=isfolder, link_attributes=link_attributes, longtitle=longtitle, menuindex=menuindex, menutitle=menutitle, pagetitleUnique=pagetitleUnique, parent=parent, published=published, pub_date=pub_date, searchable=searchable, template=template, unpub_date=unpub_date, templateVars=templateVars, resourceGroups=resourceGroups, mandatoryParents=mandatoryParents, content_type=content_type, syncsite=syncsite, ), ) @mcp_server.tool( description=( "Mettre a jour une ressource MODX. " "Attention: les nouveaux parametres ecraseront les anciens, " "meme s'ils ne sont pas renseignes; faire un get_resource au prealable." ), annotations=_WRITE_IDEMPOTENT, ) def updateResource( id: ResourceId, alias: Alias = None, cacheable: Cacheable = None, content: Content = None, deleted: Deleted = None, description: Description = None, hidemenu: Hidemenu = None, introtext: Introtext = None, isfolder: Isfolder = None, link_attributes: LinkAttributes = None, longtitle: Longtitle = None, menuindex: Menuindex = None, menutitle: Menutitle = None, pagetitle: PagetitleOpt = None, parent: Parent = None, published: Published = None, pub_date: PubDate = None, resourceGroups: ResourceGroupsUpdate = None, searchable: Searchable = None, template: TemplateId = None, templateVars: TemplateVars = None, unpub_date: UnpubDate = None, syncsite: Syncsite = None, ) -> dict[str, Any]: return client_rest.execute( method=HTTPMethod.PUT, endpoint="/rest/tools/resource", json=_omit_none( id=id, alias=alias, cacheable=cacheable, content=content, deleted=deleted, description=description, hidemenu=hidemenu, introtext=introtext, isfolder=isfolder, link_attributes=link_attributes, longtitle=longtitle, menuindex=menuindex, menutitle=menutitle, pagetitle=pagetitle, parent=parent, published=published, pub_date=pub_date, resourceGroups=resourceGroups, searchable=searchable, template=template, templateVars=templateVars, unpub_date=unpub_date, syncsite=syncsite, ), ) @mcp_server.tool( description="Supprimer une ressource MODX", annotations=_WRITE_DESTRUCTIVE, ) def deleteResource( id: ResourceIdDelete, mandatoryParent: MandatoryParent = None, syncsite: Syncsite = None, ) -> dict[str, Any]: return client_rest.execute( method=HTTPMethod.DELETE, endpoint=f"/rest/tools/resource/{id}", params=_omit_none( mandatoryParent=mandatoryParent, syncsite=syncsite, ) ) @mcp_server.tool( description="Creer un template MODX", annotations=_WRITE_ONLY, ) def createTemplate( name: TemplateName, description: TemplateDescription = None, category: Category = None, isStatic: IsStatic = None, staticFile: StaticFile = None, content: TemplateContent = None, lockTemplate: LockTemplate = None, templateVars: TemplateVarsAccess = None, ) -> dict[str, Any]: return client_rest.execute( method=HTTPMethod.POST, endpoint="/rest/tools/template", json=_omit_none( name=name, description=description, category=category, isStatic=isStatic, staticFile=staticFile, content=content, lockTemplate=lockTemplate, templateVars=templateVars, ), ) @mcp_server.tool( description=( "Mettre a jour un template MODX. " "Attention: les nouveaux parametres ecraseront les anciens; " "faire un get_template au prealable." ), annotations=_WRITE_IDEMPOTENT, ) def updateTemplate( id: TemplateIdMandatory, name: TemplateNameOpt = None, description: TemplateDescription = None, category: Category = None, isStatic: IsStatic = None, staticFile: StaticFile = None, content: TemplateContent = None, lockTemplate: LockTemplate = None, templateVars: TemplateVarsAccess = None, ) -> dict[str, Any]: return client_rest.execute( method=HTTPMethod.PUT, endpoint="/rest/tools/template", json=_omit_none( id=id, name=name, description=description, category=category, isStatic=isStatic, staticFile=staticFile, content=content, lockTemplate=lockTemplate, templateVars=templateVars, ), ) @mcp_server.tool( description="Creer une template variable MODX", annotations=_WRITE_ONLY, ) def createTv( name: TvName, description: TvDescription = None, caption: TvCaption = None, category: TvCategory = None, type: TvType = None, elements: TvElements = None, defaultText: TvDefaultText = None, lockTemplate: LockTemplate = None, inputPropeties: TvInputPropeties = None, isStatic: IsStatic = None, staticFile: StaticFile = None, templates: TvTemplates = None, ) -> dict[str, Any]: return client_rest.execute( method=HTTPMethod.POST, endpoint="/rest/tools/tv", json=_omit_none( name=name, description=description, caption=caption, category=category, type=type, elements=elements, defaultText=defaultText, lockTemplate=lockTemplate, inputPropeties=inputPropeties, isStatic=isStatic, staticFile=staticFile, templates=templates, ), ) @mcp_server.tool( description=( "Mettre a jour une template variable MODX. " "Attention: les nouveaux parametres ecraseront les anciens; " "faire un get_tv au prealable." ), annotations=_WRITE_IDEMPOTENT, ) def updateTv( id: TvId, name: TvNameOpt = None, description: TvDescription = None, caption: TvCaption = None, category: TvCategory = None, type: TvType = None, elements: TvElements = None, defaultText: TvDefaultText = None, lockTemplate: LockTemplate = None, inputPropeties: TvInputPropeties = None, isStatic: IsStatic = None, staticFile: StaticFile = None, templates: TvTemplates = None, ) -> dict[str, Any]: return client_rest.execute( method=HTTPMethod.PUT, endpoint="/rest/tools/tv", json=_omit_none( id=id, name=name, description=description, caption=caption, category=category, type=type, elements=elements, defaultText=defaultText, lockTemplate=lockTemplate, inputPropeties=inputPropeties, isStatic=isStatic, staticFile=staticFile, templates=templates, ), ) @mcp_server.tool( description="Creer une categorie MODX", annotations=_WRITE_ONLY, ) def createCategory( name: CategoryName, parent: CategoryParent = None, ) -> dict[str, Any]: return client_rest.execute( method=HTTPMethod.POST, endpoint="/rest/tools/category", json=_omit_none(name=name, parent=parent), ) @mcp_server.tool( description=( "Mettre a jour une categorie MODX. " "Attention: les nouveaux parametres ecraseront les anciens; " "faire un get_category au prealable." ), annotations=_WRITE_IDEMPOTENT, ) def updateCategory( id: CategoryId, name: CategoryNameOpt = None, parent: CategoryParent = None, ) -> dict[str, Any]: return client_rest.execute( method=HTTPMethod.PUT, endpoint="/rest/tools/category", json=_omit_none(id=id, name=name, parent=parent), )