tools.py 18 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455
  1. """Definition des outils MCP (operations d'ecriture)."""
  2. from __future__ import annotations
  3. from typing import Annotated, Any
  4. from pydantic import Field
  5. from mcp.types import ToolAnnotations
  6. from ..services.client_rest import ClientRest, HTTPMethod
  7. _WRITE_ONLY = ToolAnnotations(readOnlyHint=False, destructiveHint=False)
  8. _WRITE_DESTRUCTIVE = ToolAnnotations(readOnlyHint=False, destructiveHint=True)
  9. _WRITE_IDEMPOTENT = ToolAnnotations(
  10. readOnlyHint=False, destructiveHint=True, idempotentHint=True
  11. )
  12. # --- createResource / updateResource ---
  13. Pagetitle = Annotated[str, Field(description="page title of the resource")]
  14. PagetitleOpt = Annotated[str | None, Field(default=None, description="page title of the resource")]
  15. Alias = Annotated[str | None, Field(default=None, description="alias that will be used in the URL (default: pagetitle)")]
  16. Cacheable = Annotated[bool | None, Field(default=None, description="tells if the resource is cacheable")]
  17. Content = Annotated[str | None, Field(default=None, description="content of the resource")]
  18. ContextKey = Annotated[str | None, Field(default=None, description="context of the resource (default: web)")]
  19. Deleted = Annotated[bool | None, Field(default=None, description="tells if the resource is deleted or not")]
  20. Description = Annotated[str | None, Field(default=None, description="description of the resource")]
  21. Hidemenu = Annotated[bool | None, Field(default=None, description="tells if the resource should be hidden from menu display")]
  22. Introtext = Annotated[str | None, Field(default=None, description="introduction of the resource")]
  23. ResourceIdDuplicate = Annotated[int | None, Field(default=None, description="a resource id to duplicate")]
  24. ResourceId = Annotated[int, Field(description="a resource id to modify")]
  25. ResourceIdDelete = Annotated[int, Field(description="resource id to delete")]
  26. Isfolder = Annotated[bool | None, Field(default=None, description="tells if the resource is to be considered as a folder of resources")]
  27. LinkAttributes = Annotated[str | None, Field(default=None, description="link attributes that may be used in menu or links")]
  28. Longtitle = Annotated[str | None, Field(default=None, description="long title of the resource")]
  29. Menuindex = Annotated[int | None, Field(default=None, description="order index of the resource in a menu")]
  30. Menutitle = Annotated[str | None, Field(default=None, description="title of the resource if displayed in a menu tree")]
  31. PagetitleUnique = Annotated[
  32. 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)")]
  33. Parent = Annotated[int | None, Field(default=None, description="parent of the resource (default: 0, root)")]
  34. Published = Annotated[bool | None, Field(default=None, description="tells if the resource is published")]
  35. PubDate = Annotated[str | None, Field(default=None, description="date in the future that the resource should be published")]
  36. Searchable = Annotated[bool | None, Field(default=None, description="tells if the resource may be found in a search process")]
  37. TemplateId = Annotated[int | None, Field(default=None, description="resource id of the template (default: default_template setting, e.g. 12)")]
  38. UnpubDate = Annotated[str | None, Field(default=None, description="date when the resource should be unpublished")]
  39. TemplateVars = Annotated[dict[str, Any] | list[Any] | str | None, Field(default=None, description="json list of template variables content")]
  40. ResourceGroups = Annotated[
  41. dict[str, Any] | list[Any] | str | None,
  42. Field(default=None, description="comma-separated list of resource group ids, or JSON '[{\"id\":\"<resource id>\",\"access\":\"<0|1>\"}]'")
  43. ]
  44. ResourceGroupsUpdate = Annotated[
  45. dict[str, Any] | list[Any] | str | None,
  46. Field(default=None, description="resource groups to add; to remove a group send JSON with access=0")
  47. ]
  48. MandatoryParents = Annotated[
  49. int | str | list[int] | None,
  50. Field(default=None, description="comma-separated list of resource ids giving the authorized parents")
  51. ]
  52. ContentType = Annotated[str | None, Field(default=None, description="mime type of the resource content (default: text/html)")]
  53. Syncsite = Annotated[bool | None, Field(default=None, description="if set, it will refresh the resource cache (default: 0)")]
  54. MandatoryParent = Annotated[
  55. int | None,
  56. Field(default=None, description="set the mandatory parent of the id to verify the resource id is appropriate")
  57. ]
  58. # --- createTemplate / updateTemplate ---
  59. TemplateName = Annotated[str, Field(description="name of the template")]
  60. TemplateNameOpt = Annotated[str | None, Field(default=None, description="name of the template")]
  61. TemplateIdMandatory = Annotated[int, Field(description="id of the template")]
  62. TemplateDescription = Annotated[str | None, Field(default=None, description="description of the template")]
  63. Category = Annotated[str | None, Field(default=None, description="category the element belongs in")]
  64. IsStatic = Annotated[
  65. bool | None,
  66. Field(default=None, description="if true, the element source is stored in an external file (default: false)")
  67. ]
  68. StaticFile = Annotated[
  69. str | None,
  70. Field(default=None, description="if isStatic true, path of the external file where the element source is stored")
  71. ]
  72. TemplateContent = Annotated[str | None, Field(default=None, description="template code (HTML)")]
  73. LockTemplate = Annotated[
  74. bool | None,
  75. Field(default=None, description="lock template for editing; requires edit_locked attribute (default: false)")
  76. ]
  77. TemplateVarsAccess = Annotated[
  78. dict[str, Any] | list[Any] | str | None,
  79. Field(default=None, description="JSON list that indicates the access of template vars (default: {})")
  80. ]
  81. # --- createTv / updateTv ---
  82. TvName = Annotated[str, Field(description="name of the template variable")]
  83. TvNameOpt = Annotated[str | None, Field(default=None, description="name of the TV")]
  84. TvId = Annotated[int, Field(description="id of the TV")]
  85. TvDescription = Annotated[str | None, Field(default=None, description="description of the template variable")]
  86. TvCaption = Annotated[str | None, Field(default=None, description="text displayed beside the TV when editing it in a Resource")]
  87. TvCategory = Annotated[str | None, Field(default=None, description="category the TV belongs in")]
  88. TvType = Annotated[str | None, Field(default=None, description="the type of TV")]
  89. TvElements = Annotated[
  90. str | None,
  91. Field(default=None, description="list of options for TV; only use if the type of TV is listbox"),
  92. ]
  93. TvDefaultText = Annotated[
  94. str | None,
  95. Field(default=None, description="default option for TV; only use if the type of TV is listbox"),
  96. ]
  97. TvInputPropeties = Annotated[
  98. str | None, Field(default=None, description="JSON list of the input properties of the TV")
  99. ]
  100. TvTemplates = Annotated[
  101. dict[str, Any] | list[Any] | str | None,
  102. Field(default=None, description="JSON list that indicates the access of templates (default: {})")
  103. ]
  104. # --- createCategory / updateCategory ---
  105. CategoryName = Annotated[str, Field(description="name of the category")]
  106. CategoryNameOpt = Annotated[str | None, Field(default=None, description="name of the category")]
  107. CategoryId = Annotated[int, Field(description="id of the category")]
  108. CategoryParent = Annotated[int | None, Field(default=None, description="parent id of the category (default: 0)")]
  109. def _omit_none(**kwargs: Any) -> dict[str, Any]:
  110. return {key: value for key, value in kwargs.items() if value is not None}
  111. def register_tools(mcp_server: Any, client_rest: ClientRest) -> None:
  112. """Enregistre les outils d'ecriture du serveur MCP."""
  113. @mcp_server.tool(
  114. description="Creer une ressource MODX",
  115. annotations=_WRITE_ONLY,
  116. )
  117. def createResource(
  118. pagetitle: Pagetitle,
  119. alias: Alias = None,
  120. cacheable: Cacheable = None,
  121. content: Content = None,
  122. context_key: ContextKey = None,
  123. deleted: Deleted = None,
  124. description: Description = None,
  125. hidemenu: Hidemenu = None,
  126. introtext: Introtext = None,
  127. id: ResourceIdDuplicate = None,
  128. isfolder: Isfolder = None,
  129. link_attributes: LinkAttributes = None,
  130. longtitle: Longtitle = None,
  131. menuindex: Menuindex = None,
  132. menutitle: Menutitle = None,
  133. pagetitleUnique: PagetitleUnique = None,
  134. parent: Parent = None,
  135. published: Published = None,
  136. pub_date: PubDate = None,
  137. searchable: Searchable = None,
  138. template: TemplateId = None,
  139. unpub_date: UnpubDate = None,
  140. templateVars: TemplateVars = None,
  141. resourceGroups: ResourceGroups = None,
  142. mandatoryParents: MandatoryParents = None,
  143. content_type: ContentType = None,
  144. syncsite: Syncsite = None,
  145. ) -> dict[str, Any]:
  146. return client_rest.execute(
  147. method=HTTPMethod.POST,
  148. endpoint="/rest/tools/resource",
  149. json=_omit_none(
  150. pagetitle=pagetitle,
  151. alias=alias,
  152. cacheable=cacheable,
  153. content=content,
  154. context_key=context_key,
  155. deleted=deleted,
  156. description=description,
  157. hidemenu=hidemenu,
  158. introtext=introtext,
  159. id=id,
  160. isfolder=isfolder,
  161. link_attributes=link_attributes,
  162. longtitle=longtitle,
  163. menuindex=menuindex,
  164. menutitle=menutitle,
  165. pagetitleUnique=pagetitleUnique,
  166. parent=parent,
  167. published=published,
  168. pub_date=pub_date,
  169. searchable=searchable,
  170. template=template,
  171. unpub_date=unpub_date,
  172. templateVars=templateVars,
  173. resourceGroups=resourceGroups,
  174. mandatoryParents=mandatoryParents,
  175. content_type=content_type,
  176. syncsite=syncsite,
  177. ),
  178. )
  179. @mcp_server.tool(
  180. description=(
  181. "Mettre a jour une ressource MODX. "
  182. "Attention: les nouveaux parametres ecraseront les anciens, "
  183. "meme s'ils ne sont pas renseignes; faire un get_resource au prealable."
  184. ),
  185. annotations=_WRITE_IDEMPOTENT,
  186. )
  187. def updateResource(
  188. id: ResourceId,
  189. alias: Alias = None,
  190. cacheable: Cacheable = None,
  191. content: Content = None,
  192. deleted: Deleted = None,
  193. description: Description = None,
  194. hidemenu: Hidemenu = None,
  195. introtext: Introtext = None,
  196. isfolder: Isfolder = None,
  197. link_attributes: LinkAttributes = None,
  198. longtitle: Longtitle = None,
  199. menuindex: Menuindex = None,
  200. menutitle: Menutitle = None,
  201. pagetitle: PagetitleOpt = None,
  202. parent: Parent = None,
  203. published: Published = None,
  204. pub_date: PubDate = None,
  205. resourceGroups: ResourceGroupsUpdate = None,
  206. searchable: Searchable = None,
  207. template: TemplateId = None,
  208. templateVars: TemplateVars = None,
  209. unpub_date: UnpubDate = None,
  210. syncsite: Syncsite = None,
  211. ) -> dict[str, Any]:
  212. return client_rest.execute(
  213. method=HTTPMethod.PUT,
  214. endpoint="/rest/tools/resource",
  215. json=_omit_none(
  216. id=id,
  217. alias=alias,
  218. cacheable=cacheable,
  219. content=content,
  220. deleted=deleted,
  221. description=description,
  222. hidemenu=hidemenu,
  223. introtext=introtext,
  224. isfolder=isfolder,
  225. link_attributes=link_attributes,
  226. longtitle=longtitle,
  227. menuindex=menuindex,
  228. menutitle=menutitle,
  229. pagetitle=pagetitle,
  230. parent=parent,
  231. published=published,
  232. pub_date=pub_date,
  233. resourceGroups=resourceGroups,
  234. searchable=searchable,
  235. template=template,
  236. templateVars=templateVars,
  237. unpub_date=unpub_date,
  238. syncsite=syncsite,
  239. ),
  240. )
  241. @mcp_server.tool(
  242. description="Supprimer une ressource MODX",
  243. annotations=_WRITE_DESTRUCTIVE,
  244. )
  245. def deleteResource(
  246. id: ResourceIdDelete,
  247. mandatoryParent: MandatoryParent = None,
  248. syncsite: Syncsite = None,
  249. ) -> dict[str, Any]:
  250. return client_rest.execute(
  251. method=HTTPMethod.DELETE,
  252. endpoint=f"/rest/tools/resource/{id}",
  253. params=_omit_none(
  254. mandatoryParent=mandatoryParent,
  255. syncsite=syncsite,
  256. )
  257. )
  258. @mcp_server.tool(
  259. description="Creer un template MODX",
  260. annotations=_WRITE_ONLY,
  261. )
  262. def createTemplate(
  263. name: TemplateName,
  264. description: TemplateDescription = None,
  265. category: Category = None,
  266. isStatic: IsStatic = None,
  267. staticFile: StaticFile = None,
  268. content: TemplateContent = None,
  269. lockTemplate: LockTemplate = None,
  270. templateVars: TemplateVarsAccess = None,
  271. ) -> dict[str, Any]:
  272. return client_rest.execute(
  273. method=HTTPMethod.POST,
  274. endpoint="/rest/tools/template",
  275. json=_omit_none(
  276. name=name,
  277. description=description,
  278. category=category,
  279. isStatic=isStatic,
  280. staticFile=staticFile,
  281. content=content,
  282. lockTemplate=lockTemplate,
  283. templateVars=templateVars,
  284. ),
  285. )
  286. @mcp_server.tool(
  287. description=(
  288. "Mettre a jour un template MODX. "
  289. "Attention: les nouveaux parametres ecraseront les anciens; "
  290. "faire un get_template au prealable."
  291. ),
  292. annotations=_WRITE_IDEMPOTENT,
  293. )
  294. def updateTemplate(
  295. id: TemplateIdMandatory,
  296. name: TemplateNameOpt = None,
  297. description: TemplateDescription = None,
  298. category: Category = None,
  299. isStatic: IsStatic = None,
  300. staticFile: StaticFile = None,
  301. content: TemplateContent = None,
  302. lockTemplate: LockTemplate = None,
  303. templateVars: TemplateVarsAccess = None,
  304. ) -> dict[str, Any]:
  305. return client_rest.execute(
  306. method=HTTPMethod.PUT,
  307. endpoint="/rest/tools/template",
  308. json=_omit_none(
  309. id=id,
  310. name=name,
  311. description=description,
  312. category=category,
  313. isStatic=isStatic,
  314. staticFile=staticFile,
  315. content=content,
  316. lockTemplate=lockTemplate,
  317. templateVars=templateVars,
  318. ),
  319. )
  320. @mcp_server.tool(
  321. description="Creer une template variable MODX",
  322. annotations=_WRITE_ONLY,
  323. )
  324. def createTv(
  325. name: TvName,
  326. description: TvDescription = None,
  327. caption: TvCaption = None,
  328. category: TvCategory = None,
  329. type: TvType = None,
  330. elements: TvElements = None,
  331. defaultText: TvDefaultText = None,
  332. lockTemplate: LockTemplate = None,
  333. inputPropeties: TvInputPropeties = None,
  334. isStatic: IsStatic = None,
  335. staticFile: StaticFile = None,
  336. templates: TvTemplates = None,
  337. ) -> dict[str, Any]:
  338. return client_rest.execute(
  339. method=HTTPMethod.POST,
  340. endpoint="/rest/tools/tv",
  341. json=_omit_none(
  342. name=name,
  343. description=description,
  344. caption=caption,
  345. category=category,
  346. type=type,
  347. elements=elements,
  348. defaultText=defaultText,
  349. lockTemplate=lockTemplate,
  350. inputPropeties=inputPropeties,
  351. isStatic=isStatic,
  352. staticFile=staticFile,
  353. templates=templates,
  354. ),
  355. )
  356. @mcp_server.tool(
  357. description=(
  358. "Mettre a jour une template variable MODX. "
  359. "Attention: les nouveaux parametres ecraseront les anciens; "
  360. "faire un get_tv au prealable."
  361. ),
  362. annotations=_WRITE_IDEMPOTENT,
  363. )
  364. def updateTv(
  365. id: TvId,
  366. name: TvNameOpt = None,
  367. description: TvDescription = None,
  368. caption: TvCaption = None,
  369. category: TvCategory = None,
  370. type: TvType = None,
  371. elements: TvElements = None,
  372. defaultText: TvDefaultText = None,
  373. lockTemplate: LockTemplate = None,
  374. inputPropeties: TvInputPropeties = None,
  375. isStatic: IsStatic = None,
  376. staticFile: StaticFile = None,
  377. templates: TvTemplates = None,
  378. ) -> dict[str, Any]:
  379. return client_rest.execute(
  380. method=HTTPMethod.PUT,
  381. endpoint="/rest/tools/tv",
  382. json=_omit_none(
  383. id=id,
  384. name=name,
  385. description=description,
  386. caption=caption,
  387. category=category,
  388. type=type,
  389. elements=elements,
  390. defaultText=defaultText,
  391. lockTemplate=lockTemplate,
  392. inputPropeties=inputPropeties,
  393. isStatic=isStatic,
  394. staticFile=staticFile,
  395. templates=templates,
  396. ),
  397. )
  398. @mcp_server.tool(
  399. description="Creer une categorie MODX",
  400. annotations=_WRITE_ONLY,
  401. )
  402. def createCategory(
  403. name: CategoryName,
  404. parent: CategoryParent = None,
  405. ) -> dict[str, Any]:
  406. return client_rest.execute(
  407. method=HTTPMethod.POST,
  408. endpoint="/rest/tools/category",
  409. json=_omit_none(name=name, parent=parent),
  410. )
  411. @mcp_server.tool(
  412. description=(
  413. "Mettre a jour une categorie MODX. "
  414. "Attention: les nouveaux parametres ecraseront les anciens; "
  415. "faire un get_category au prealable."
  416. ),
  417. annotations=_WRITE_IDEMPOTENT,
  418. )
  419. def updateCategory(
  420. id: CategoryId,
  421. name: CategoryNameOpt = None,
  422. parent: CategoryParent = None,
  423. ) -> dict[str, Any]:
  424. return client_rest.execute(
  425. method=HTTPMethod.PUT,
  426. endpoint="/rest/tools/category",
  427. json=_omit_none(id=id, name=name, parent=parent),
  428. )