@charisol/plexo-mcp 1.0.16 → 1.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -8,7 +8,8 @@ Connect **Claude Desktop**, **Claude Web**, **ChatGPT**, **Cursor**, **Windsurf*
8
8
 
9
9
  ## Capabilities & Tools
10
10
 
11
- - 🚀 **`publish_landing_page`**: Creates, compiles, and publishes a landing page (JSON schema + HTML) to a subdomain or custom domain in 1 step.
11
+ - 🧱 **Building pages (V2)** — `page_create_from_template`, `page_describe`, `page_edit`, `page_publish`, `blog_layout_describe`, `blog_layout_edit`: visual pages and sites the owner can keep editing in Plexo's visual editor. See [Building pages (V2)](#building-pages-v2).
12
+ - 🚀 **`publish_landing_page`** *(deprecated)*: Creates, compiles, and publishes a landing page (JSON schema + HTML) to a subdomain or custom domain in 1 step.
12
13
  - ✉️ **`create_email_template`**: Creates and saves a responsive email template (same JSON schema as landing pages, no domain).
13
14
  - ✏️ **`update_template`**: Edits an existing landing page or email template in place, under the same template ID.
14
15
  - 📄 **`list_landing_pages`**: Retrieves saved landing page designs and active domain URLs.
@@ -67,9 +68,27 @@ If `PLEXO_API_KEY` is omitted, the tool cleanly prompts:
67
68
 
68
69
  ---
69
70
 
71
+ ## Building pages (V2)
72
+
73
+ Everything visual an assistant builds with Plexo — landing pages, whole sites, a blog's look — is a **V2** page, made of ready-made sections the owner can keep editing in Plexo's visual editor. The workflow is always the same:
74
+
75
+ 1. **`page_create_from_template`** `{ name, templateId?, siteId?, content? }` — starts a complete, filled-in page from a ready-made template (`blank`, `home`, `landing`, `about`, `services`, `contact`, `pricing`). Without `siteId` it starts a new site; with `siteId` it adds a page to that site (Ultra plan). `content` takes the same section commands as `page_edit`, so you can add the business's real copy and brand colours in the same call. Nothing is published yet.
76
+ 2. **`page_describe`** `{ templateId | siteId, slug?, includeCatalog? }` — the site's pages, the page's sections (ids, kinds, a few words of each), the brand, and the catalog of every section kind (including blog, shop and funnel sections) and page template.
77
+ 3. **`page_edit`** `{ templateId, commands[], slug? }` — section commands: `addSection`, `updateSection`, `removeSection`, `moveSection`, `duplicateSection`, `setBrand`, `renamePage`. Each command is checked on its own (good ones are saved, bad ones come back with a plain-English reason). Changes are saved as the page's working copy, exactly like the editor's autosave.
78
+ 4. **`page_publish`** `{ templateId, domain?, type? }` — puts the latest changes live; for a site's home page pass a `domain` (a short subdomain or the owner's own). If the site has no address yet the reply lists `suggestedDomains`.
79
+
80
+ Blog post and listing layouts use **`blog_layout_describe`** / **`blog_layout_edit`** `{ templateId, kind: "post" | "listing", commands[] }` the same way.
81
+
82
+ Write real, specific copy for the business — never placeholder text. Email templates are unchanged and still use `create_email_template` / `update_template`.
83
+
84
+ ### Deprecated tools (90 days)
85
+
86
+ `create_landing_page`, `publish_landing_page`, `update_template`, `create_landing_page_subpage`, `design_blog_layout`, `get_blog_layout` and the raw-HTML tools (`create_raw_landing_page`, `publish_raw_landing_page`, `update_raw_landing_page`) still work for classic and raw-HTML pages, but their descriptions start with `[DEPRECATED …]` and their results carry a `deprecation` field naming the replacement. Pointing one of them at a V2 page returns a plain-language message naming `page_describe` / `page_edit` / `page_publish`. Raw-HTML pages are advanced and **not editable in the visual editor** — only use them when the owner explicitly asks for hand-written HTML.
87
+
70
88
  ## Example AI Prompts
71
89
 
72
- - *"Generate a modern tech SaaS landing page for an AI CRM called Acme and publish it using Plexo to subdomain acme-crm"*
90
+ - *"Build a landing page for my bakery, make the brand warm and publish it to subdomain sunrise-bakery"*
91
+ - *"On my pricing page, change the headline and add an FAQ section"*
73
92
  - *"Show me my page view analytics for the last 7 days"*
74
93
  - *"List all my email templates"*
75
94
  - *"Move my WordPress site example.org to Plexo"*
@@ -349,6 +349,63 @@ exports.APP_TOOL_DEFS = [
349
349
  ]
350
350
  }
351
351
  },
352
+ {
353
+ "name": "app_design_describe",
354
+ "description": "Reads the app's visually designed pages (the Design tab, src/plexo-canvas): for each page its slug, name, address and its sections in order (id, kind, layout, a few words of what it says), plus the brand (colours, fonts, corners) and the catalog of every section kind with its layouts and the fields you can fill in, and the ready-made page templates. Call this before app_design_edit, and again after you change a page if you need fresh section ids. Pages marked codeEdited were changed in code — edit those with app_edit_file, not app_design_edit.",
355
+ "inputSchema": {
356
+ "type": "object",
357
+ "properties": {
358
+ "appId": {
359
+ "type": "string",
360
+ "description": "The app's id (from create_app or list_apps)."
361
+ }
362
+ },
363
+ "required": [
364
+ "appId"
365
+ ]
366
+ }
367
+ },
368
+ {
369
+ "name": "app_design_edit",
370
+ "description": "Changes designed pages section by section — the right way to edit a page built in the Design tab, instead of editing its generated .tsx. Pass commands, each one of: {op:\"addSection\", pageId, kind, variant?, content?, style?, afterSectionId? | index?} · {op:\"updateSection\", sectionId, content?, variant?, style?} · {op:\"removeSection\", sectionId} · {op:\"moveSection\", sectionId, index? | afterSectionId?} · {op:\"duplicateSection\", sectionId} · {op:\"setBrand\", tokens:{primaryColor?, secondaryColor?, headingFont?, bodyFont?, neutrals? (cool|warm|dark), roundness? (sharp|soft|round)}} · {op:\"addPage\", name, templateId?} (templateId from the catalog: home, landing, about, services, contact, pricing, blank — gives a complete, filled-in page) · {op:\"renamePage\", pageId, name}. pageId is the page's slug from app_design_describe; sectionId is a section id from it. Content keys are the field paths from the catalog (\"headline\", \"items.0.title\"); a list field needs the whole list; write real copy for the business. Each command is checked on its own — good ones are saved, bad ones come back with a plain-English reason, so read results. slug (optional) is the page you're working on: an addSection without a pageId goes there. A page that was edited in code is not changed (the reply says so); only pass overwrite: true if the owner chose to replace their code edits. Saving regenerates the page's React code and its route. Run app_build afterwards, then app_screenshot.",
371
+ "inputSchema": {
372
+ "type": "object",
373
+ "properties": {
374
+ "appId": {
375
+ "type": "string",
376
+ "description": "The app's id (from create_app or list_apps)."
377
+ },
378
+ "slug": {
379
+ "type": "string",
380
+ "description": "The designed page being edited (from app_design_describe)."
381
+ },
382
+ "commands": {
383
+ "type": "array",
384
+ "maxItems": 40,
385
+ "items": {
386
+ "type": "object",
387
+ "properties": {
388
+ "op": {
389
+ "type": "string"
390
+ }
391
+ },
392
+ "required": [
393
+ "op"
394
+ ],
395
+ "additionalProperties": true
396
+ }
397
+ },
398
+ "overwrite": {
399
+ "type": "boolean",
400
+ "description": "Replace hand edits made to the page's code. Only when the owner asked for it."
401
+ }
402
+ },
403
+ "required": [
404
+ "appId",
405
+ "commands"
406
+ ]
407
+ }
408
+ },
352
409
  {
353
410
  "name": "app_publish",
354
411
  "description": "Publishes the app: a clean release build, then the live database gets new migrations, server functions are deployed, and the live site switches over. The first publish gives it an address (subdomain picked from the app's name unless given). Only after the preview builds cleanly and the owner wants it live.",
@@ -0,0 +1,53 @@
1
+ "use strict";
2
+ // Mirrors plexo-web lib/mcp/deprecation.ts. The classic (V1) and raw-HTML page tools keep
3
+ // working for 90 days; their descriptions start with this notice and their results carry a
4
+ // `deprecation` field. Email templates are not deprecated — email stays on the classic editor.
5
+ Object.defineProperty(exports, "__esModule", { value: true });
6
+ exports.DEPRECATED_TOOLS = exports.DEPRECATED_PREFIX = exports.DEPRECATION_WINDOW_DAYS = void 0;
7
+ exports.markDeprecated = markDeprecated;
8
+ exports.addDeprecation = addDeprecation;
9
+ exports.DEPRECATION_WINDOW_DAYS = 90;
10
+ exports.DEPRECATED_PREFIX = "[DEPRECATED — use page_create_from_template / page_edit / page_publish for landing pages and sites] ";
11
+ const RAW_NOTICE = "ADVANCED, NOT VISUAL — a raw-HTML page is not editable in Plexo's visual editor, so the owner can never tweak it themselves. Only use this when the owner explicitly asked for hand-written HTML; for any normal page or site use page_create_from_template instead. ";
12
+ exports.DEPRECATED_TOOLS = {
13
+ create_landing_page: { replacement: "page_create_from_template" },
14
+ publish_landing_page: { replacement: "page_create_from_template + page_publish" },
15
+ update_template: { replacement: "page_describe + page_edit" },
16
+ create_landing_page_subpage: { replacement: "page_create_from_template (with siteId)" },
17
+ design_blog_layout: { replacement: "blog_layout_describe + blog_layout_edit" },
18
+ get_blog_layout: { replacement: "blog_layout_describe" },
19
+ create_raw_landing_page: { replacement: "page_create_from_template", raw: true },
20
+ publish_raw_landing_page: { replacement: "page_create_from_template + page_publish", raw: true },
21
+ update_raw_landing_page: { replacement: "page_describe + page_edit", raw: true },
22
+ };
23
+ function markDeprecated(tool) {
24
+ const info = exports.DEPRECATED_TOOLS[tool.name];
25
+ if (!info)
26
+ return tool;
27
+ return { ...tool, description: `${exports.DEPRECATED_PREFIX}${info.raw ? RAW_NOTICE : ""}${tool.description ?? ""}` };
28
+ }
29
+ /** Adds `deprecation` to a deprecated tool's successful JSON-text result (the plexo-web hosted tools add their own). */
30
+ function addDeprecation(name, response) {
31
+ const info = exports.DEPRECATED_TOOLS[name];
32
+ const first = response?.content?.[0];
33
+ if (!info || response.isError || !first || first.type !== "text" || typeof first.text !== "string")
34
+ return response;
35
+ try {
36
+ const parsed = JSON.parse(first.text);
37
+ if (!parsed || typeof parsed !== "object" || Array.isArray(parsed) || parsed.deprecation)
38
+ return response;
39
+ const withNotice = {
40
+ ...parsed,
41
+ deprecation: {
42
+ tool: name,
43
+ replacement: info.replacement,
44
+ removalAfterDays: exports.DEPRECATION_WINDOW_DAYS,
45
+ message: `${name} still works for classic, email and raw-HTML pages but will be removed in ${exports.DEPRECATION_WINDOW_DAYS} days. Use ${info.replacement} instead — pages built that way stay editable in Plexo's visual editor.`,
46
+ },
47
+ };
48
+ return { ...response, content: [{ ...first, text: JSON.stringify(withNotice, null, 2) }, ...response.content.slice(1)] };
49
+ }
50
+ catch {
51
+ return response;
52
+ }
53
+ }
package/dist/index.js CHANGED
@@ -12,6 +12,8 @@ const donationTools_js_1 = require("./donationTools.js");
12
12
  const wpMigrationTools_js_1 = require("./wpMigrationTools.js");
13
13
  const formTools_js_1 = require("./formTools.js");
14
14
  const appTools_js_1 = require("./appTools.js");
15
+ const pageTools_js_1 = require("./pageTools.js");
16
+ const deprecation_js_1 = require("./deprecation.js");
15
17
  const server = new index_js_1.Server({
16
18
  name: "plexo-mcp",
17
19
  version: "1.0.0",
@@ -651,11 +653,12 @@ To edit a page's CONTENT (designJson), use update_template with the same templat
651
653
  ...wpMigrationTools_js_1.WP_MIGRATION_TOOL_DEFS,
652
654
  ...formTools_js_1.FORM_TOOL_DEFS,
653
655
  ...appTools_js_1.APP_TOOL_DEFS,
654
- ],
656
+ ...pageTools_js_1.PAGE_TOOL_DEFS,
657
+ ].map(deprecation_js_1.markDeprecated),
655
658
  };
656
659
  });
657
660
  // Implement tool handlers
658
- server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
661
+ const handleToolCall = async (request) => {
659
662
  const { name, arguments: args } = request.params;
660
663
  const client = new plexoClient_js_1.PlexoClient();
661
664
  try {
@@ -930,6 +933,9 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
930
933
  if (appTools_js_1.APP_TOOL_NAMES.has(name)) {
931
934
  return await (0, appTools_js_1.callHostedAppTool)(name, args);
932
935
  }
936
+ if (pageTools_js_1.PAGE_TOOL_NAMES.has(name)) {
937
+ return await (0, pageTools_js_1.callHostedPageTool)(name, args);
938
+ }
933
939
  for (const [names, handler] of [
934
940
  [donationTools_js_1.DONATION_TOOL_NAMES, donationTools_js_1.handleDonationToolCall],
935
941
  [wpMigrationTools_js_1.WP_MIGRATION_TOOL_NAMES, wpMigrationTools_js_1.handleWpMigrationToolCall],
@@ -955,7 +961,8 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
955
961
  isError: true,
956
962
  };
957
963
  }
958
- });
964
+ };
965
+ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => (0, deprecation_js_1.addDeprecation)(request.params.name, (await handleToolCall(request))));
959
966
  async function run() {
960
967
  const transport = new stdio_js_1.StdioServerTransport();
961
968
  await server.connect(transport);
@@ -0,0 +1,221 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.PAGE_TOOL_DEFS = void 0;
4
+ // Mirrors plexo-web lib/mcp/pageTools.ts (the definitions only — every call is executed by
5
+ // plexo-web itself, see pageTools.ts). Regenerate when that file changes.
6
+ exports.PAGE_TOOL_DEFS = [
7
+ {
8
+ "name": "page_describe",
9
+ "description": "START HERE for any landing page or site. Shows a site's pages (name, slug, address, whether each uses the new visual editor) and, for a visual (V2) page, its sections in order (id, kind, layout, a few words of what each says), the brand (colours, fonts, corners) and the catalog of everything you can add — every section kind with its layouts and fillable fields, the ready-made page templates (blank, home, landing, about, services, contact, pricing), and the blog, shop and funnel sections. Pass templateId (or siteId — the home page's id) and optionally slug to look at one of the site's other pages. Call it before page_edit, and again after edits if you need fresh section ids. Pass includeCatalog:false on later calls to keep the reply short. The workflow is: page_describe → page_edit with section commands → page_publish.",
10
+ "inputSchema": {
11
+ "type": "object",
12
+ "properties": {
13
+ "templateId": {
14
+ "type": "string",
15
+ "description": "A page's id — or the site's home page id to see the whole site."
16
+ },
17
+ "siteId": {
18
+ "type": "string",
19
+ "description": "The site's home page id (same as templateId; use whichever you have)."
20
+ },
21
+ "slug": {
22
+ "type": "string",
23
+ "description": "Optional: a page of the site by its address segment, e.g. \"about\", when templateId/siteId is the site's home page."
24
+ },
25
+ "includeCatalog": {
26
+ "type": "boolean",
27
+ "description": "Default true. Pass false once you already know the catalog."
28
+ }
29
+ }
30
+ }
31
+ },
32
+ {
33
+ "name": "page_edit",
34
+ "description": "Changes a visual page section by section — the way to edit any page made with page_create_from_template (and any page the owner designed in the visual editor). Saves it as the page's working copy in the editor (exactly what the editor's own autosave does); nothing goes live until page_publish. Each command is one of: {op:\"addSection\", kind, variant?, content?, style?, afterSectionId? | index?} · {op:\"updateSection\", sectionId, content?, variant?, style?} · {op:\"removeSection\", sectionId} · {op:\"moveSection\", sectionId, index? | afterSectionId?} · {op:\"duplicateSection\", sectionId} · {op:\"setBrand\", tokens:{primaryColor?, secondaryColor?, headingFont?, bodyFont?, neutrals? (cool|warm|dark), roundness? (sharp|soft|round)}} · {op:\"renamePage\", name}. kind/variant and the content field paths (\"headline\", \"items.0.title\") come from the catalog in page_describe; a list field needs the whole list; style is {background? (canvas|surface|sunken|primary|inverted|gradient|image), align? (left|center), spacing? (tight|normal|airy)}. sectionId values come from page_describe and are only valid for that page. Write real, specific copy for the business — never lorem ipsum. Each command is checked on its own: good ones are saved, bad ones come back with a plain-English reason, so read the results and resend only the ones that failed. Up to 40 commands per call. To add a whole new page to the site use page_create_from_template with siteId — an addPage command here is declined with that hint. Pages built with the classic tools (create_landing_page etc.) or as raw HTML can't be edited with this.",
35
+ "inputSchema": {
36
+ "type": "object",
37
+ "properties": {
38
+ "templateId": {
39
+ "type": "string",
40
+ "description": "The page's templateId (from page_create_from_template, list_landing_pages or get_landing_page_pages). For a site's home page this is also the siteId."
41
+ },
42
+ "slug": {
43
+ "type": "string",
44
+ "description": "Optional: edit the site's page with this address segment instead of templateId's own page."
45
+ },
46
+ "commands": {
47
+ "type": "array",
48
+ "maxItems": 40,
49
+ "items": {
50
+ "type": "object",
51
+ "properties": {
52
+ "op": {
53
+ "type": "string"
54
+ }
55
+ },
56
+ "required": [
57
+ "op"
58
+ ],
59
+ "additionalProperties": true
60
+ }
61
+ }
62
+ },
63
+ "required": [
64
+ "templateId",
65
+ "commands"
66
+ ]
67
+ }
68
+ },
69
+ {
70
+ "name": "page_create_from_template",
71
+ "description": "Creates a visual page that is already complete: header, sections and footer all filled in with starting wording. Without siteId it starts a NEW SITE (this is its home page); with siteId it adds a page to that site (Ultra plan). templateId is a page template: blank, home, landing, about, services, contact or pricing (home for a first page, landing for a one-page sales site). Pass content — the same commands as page_edit — to personalise it in the same call (headline, copy, brand colours with setBrand), so the owner sees a finished page for their business straight away; any wording you don't change stays as the template's sample text, so replace the key copy. It isn't published: call page_publish with a domain when the owner is ready. Never ask the owner for a name or address first — name the page yourself from what it's about.",
72
+ "inputSchema": {
73
+ "type": "object",
74
+ "properties": {
75
+ "name": {
76
+ "type": "string",
77
+ "description": "Page name, e.g. \"Home\", \"Pricing\" or the business's name for a new site."
78
+ },
79
+ "templateId": {
80
+ "type": "string",
81
+ "enum": [
82
+ "blank",
83
+ "home",
84
+ "landing",
85
+ "about",
86
+ "services",
87
+ "contact",
88
+ "pricing"
89
+ ],
90
+ "description": "Which ready-made page to start from. Default home."
91
+ },
92
+ "siteId": {
93
+ "type": "string",
94
+ "description": "Add the page to this existing visual site (its home page id). Omit to start a new site."
95
+ },
96
+ "content": {
97
+ "type": "array",
98
+ "maxItems": 40,
99
+ "items": {
100
+ "type": "object",
101
+ "properties": {
102
+ "op": {
103
+ "type": "string"
104
+ }
105
+ },
106
+ "required": [
107
+ "op"
108
+ ],
109
+ "additionalProperties": true
110
+ },
111
+ "description": "Optional page_edit commands applied right after creating the page. Section ids don't exist yet, so use addSection / setBrand, or call page_describe first to get ids for updateSection."
112
+ }
113
+ },
114
+ "required": [
115
+ "name"
116
+ ]
117
+ }
118
+ },
119
+ {
120
+ "name": "page_publish",
121
+ "description": "Puts a visual page's latest changes live (and keeps the previous version in its history). For a site's home page, also pass domain to give it an address: a short subdomain like \"careconnect\" (becomes careconnect.<pages domain>) or the owner's own domain. Other pages of the site go live at that same address automatically (e.g. /about) once the home page has a domain — publish them too so their latest edits are live. If the home page has no address yet and none is given, the reply lists suggestedDomains to offer the owner. Free plans publish only the home page on a Plexo address and one live site; the reply says plainly when a limit applies.",
122
+ "inputSchema": {
123
+ "type": "object",
124
+ "properties": {
125
+ "templateId": {
126
+ "type": "string",
127
+ "description": "The page's templateId (from page_create_from_template, list_landing_pages or get_landing_page_pages). For a site's home page this is also the siteId."
128
+ },
129
+ "domain": {
130
+ "type": "string",
131
+ "description": "Home page only. Subdomain slug (e.g. 'kicks') or custom domain ('kicks.com')."
132
+ },
133
+ "type": {
134
+ "type": "string",
135
+ "enum": [
136
+ "SUBDOMAIN",
137
+ "CUSTOM"
138
+ ],
139
+ "description": "Inferred from the domain string if omitted."
140
+ }
141
+ },
142
+ "required": [
143
+ "templateId"
144
+ ]
145
+ }
146
+ },
147
+ {
148
+ "name": "blog_layout_describe",
149
+ "description": "Shows a blog's custom post page or listing (index) page layout built with the visual editor: its sections, the brand and the catalog (the blogArticle section is the post body, blogList the list of posts). If the blog has no custom layout yet it says so and what blog_layout_edit will start from. Use before blog_layout_edit.",
150
+ "inputSchema": {
151
+ "type": "object",
152
+ "properties": {
153
+ "templateId": {
154
+ "type": "string",
155
+ "description": "The blog site's home page id."
156
+ },
157
+ "kind": {
158
+ "type": "string",
159
+ "enum": [
160
+ "post",
161
+ "listing"
162
+ ],
163
+ "description": "post = a single article's page; listing = the blog index."
164
+ },
165
+ "includeCatalog": {
166
+ "type": "boolean",
167
+ "description": "Default true. Pass false once you know the catalog."
168
+ }
169
+ },
170
+ "required": [
171
+ "templateId",
172
+ "kind"
173
+ ]
174
+ }
175
+ },
176
+ {
177
+ "name": "blog_layout_edit",
178
+ "description": "Designs a blog's post page or listing page with the visual editor, using the same section commands as page_edit. Creates the layout the first time (an empty page you fill with commands). A post layout needs a blogArticle section and a listing layout needs a blogList section — until it has one the blog falls back to the default theme, and the reply warns about it. Typical post layout: header, blogArticle, cta, footer. Takes effect immediately (blog layouts have no separate publish step). Each command is one of: {op:\"addSection\", kind, variant?, content?, style?, afterSectionId? | index?} · {op:\"updateSection\", sectionId, content?, variant?, style?} · {op:\"removeSection\", sectionId} · {op:\"moveSection\", sectionId, index? | afterSectionId?} · {op:\"duplicateSection\", sectionId} · {op:\"setBrand\", tokens:{primaryColor?, secondaryColor?, headingFont?, bodyFont?, neutrals? (cool|warm|dark), roundness? (sharp|soft|round)}} · {op:\"renamePage\", name}. kind/variant and the content field paths (\"headline\", \"items.0.title\") come from the catalog in page_describe; a list field needs the whole list; style is {background? (canvas|surface|sunken|primary|inverted|gradient|image), align? (left|center), spacing? (tight|normal|airy)}. sectionId values come from page_describe and are only valid for that page. Write real, specific copy for the business — never lorem ipsum. Each command is checked on its own: good ones are saved, bad ones come back with a plain-English reason, so read the results and resend only the ones that failed.",
179
+ "inputSchema": {
180
+ "type": "object",
181
+ "properties": {
182
+ "templateId": {
183
+ "type": "string",
184
+ "description": "The blog site's home page id."
185
+ },
186
+ "kind": {
187
+ "type": "string",
188
+ "enum": [
189
+ "post",
190
+ "listing"
191
+ ]
192
+ },
193
+ "commands": {
194
+ "type": "array",
195
+ "maxItems": 40,
196
+ "items": {
197
+ "type": "object",
198
+ "properties": {
199
+ "op": {
200
+ "type": "string"
201
+ }
202
+ },
203
+ "required": [
204
+ "op"
205
+ ],
206
+ "additionalProperties": true
207
+ }
208
+ },
209
+ "startFresh": {
210
+ "type": "boolean",
211
+ "description": "Only if the blog's current layout was built in the classic editor and has content: true replaces it. Ask the owner first."
212
+ }
213
+ },
214
+ "required": [
215
+ "templateId",
216
+ "kind",
217
+ "commands"
218
+ ]
219
+ }
220
+ }
221
+ ];
@@ -0,0 +1,8 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.callHostedPageTool = exports.PAGE_TOOL_NAMES = exports.PAGE_TOOL_DEFS = void 0;
4
+ const pageToolDefs_js_1 = require("./pageToolDefs.js");
5
+ Object.defineProperty(exports, "PAGE_TOOL_DEFS", { enumerable: true, get: function () { return pageToolDefs_js_1.PAGE_TOOL_DEFS; } });
6
+ const appTools_js_1 = require("./appTools.js");
7
+ exports.PAGE_TOOL_NAMES = new Set(pageToolDefs_js_1.PAGE_TOOL_DEFS.map((t) => t.name));
8
+ exports.callHostedPageTool = appTools_js_1.callHostedAppTool;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@charisol/plexo-mcp",
3
- "version": "1.0.16",
3
+ "version": "1.1.1",
4
4
  "description": "Model Context Protocol (MCP) Server for Plexo - Landing page generation, email templates, publishing, and analytics.",
5
5
  "main": "dist/index.js",
6
6
  "bin": {
@@ -346,6 +346,63 @@ export const APP_TOOL_DEFS = [
346
346
  ]
347
347
  }
348
348
  },
349
+ {
350
+ "name": "app_design_describe",
351
+ "description": "Reads the app's visually designed pages (the Design tab, src/plexo-canvas): for each page its slug, name, address and its sections in order (id, kind, layout, a few words of what it says), plus the brand (colours, fonts, corners) and the catalog of every section kind with its layouts and the fields you can fill in, and the ready-made page templates. Call this before app_design_edit, and again after you change a page if you need fresh section ids. Pages marked codeEdited were changed in code — edit those with app_edit_file, not app_design_edit.",
352
+ "inputSchema": {
353
+ "type": "object",
354
+ "properties": {
355
+ "appId": {
356
+ "type": "string",
357
+ "description": "The app's id (from create_app or list_apps)."
358
+ }
359
+ },
360
+ "required": [
361
+ "appId"
362
+ ]
363
+ }
364
+ },
365
+ {
366
+ "name": "app_design_edit",
367
+ "description": "Changes designed pages section by section — the right way to edit a page built in the Design tab, instead of editing its generated .tsx. Pass commands, each one of: {op:\"addSection\", pageId, kind, variant?, content?, style?, afterSectionId? | index?} · {op:\"updateSection\", sectionId, content?, variant?, style?} · {op:\"removeSection\", sectionId} · {op:\"moveSection\", sectionId, index? | afterSectionId?} · {op:\"duplicateSection\", sectionId} · {op:\"setBrand\", tokens:{primaryColor?, secondaryColor?, headingFont?, bodyFont?, neutrals? (cool|warm|dark), roundness? (sharp|soft|round)}} · {op:\"addPage\", name, templateId?} (templateId from the catalog: home, landing, about, services, contact, pricing, blank — gives a complete, filled-in page) · {op:\"renamePage\", pageId, name}. pageId is the page's slug from app_design_describe; sectionId is a section id from it. Content keys are the field paths from the catalog (\"headline\", \"items.0.title\"); a list field needs the whole list; write real copy for the business. Each command is checked on its own — good ones are saved, bad ones come back with a plain-English reason, so read results. slug (optional) is the page you're working on: an addSection without a pageId goes there. A page that was edited in code is not changed (the reply says so); only pass overwrite: true if the owner chose to replace their code edits. Saving regenerates the page's React code and its route. Run app_build afterwards, then app_screenshot.",
368
+ "inputSchema": {
369
+ "type": "object",
370
+ "properties": {
371
+ "appId": {
372
+ "type": "string",
373
+ "description": "The app's id (from create_app or list_apps)."
374
+ },
375
+ "slug": {
376
+ "type": "string",
377
+ "description": "The designed page being edited (from app_design_describe)."
378
+ },
379
+ "commands": {
380
+ "type": "array",
381
+ "maxItems": 40,
382
+ "items": {
383
+ "type": "object",
384
+ "properties": {
385
+ "op": {
386
+ "type": "string"
387
+ }
388
+ },
389
+ "required": [
390
+ "op"
391
+ ],
392
+ "additionalProperties": true
393
+ }
394
+ },
395
+ "overwrite": {
396
+ "type": "boolean",
397
+ "description": "Replace hand edits made to the page's code. Only when the owner asked for it."
398
+ }
399
+ },
400
+ "required": [
401
+ "appId",
402
+ "commands"
403
+ ]
404
+ }
405
+ },
349
406
  {
350
407
  "name": "app_publish",
351
408
  "description": "Publishes the app: a clean release build, then the live database gets new migrations, server functions are deployed, and the live site switches over. The first publish gives it an address (subdomain picked from the app's name unless given). Only after the preview builds cleanly and the owner wants it live.",
@@ -0,0 +1,52 @@
1
+ // Mirrors plexo-web lib/mcp/deprecation.ts. The classic (V1) and raw-HTML page tools keep
2
+ // working for 90 days; their descriptions start with this notice and their results carry a
3
+ // `deprecation` field. Email templates are not deprecated — email stays on the classic editor.
4
+
5
+ export const DEPRECATION_WINDOW_DAYS = 90;
6
+
7
+ export const DEPRECATED_PREFIX =
8
+ "[DEPRECATED — use page_create_from_template / page_edit / page_publish for landing pages and sites] ";
9
+
10
+ const RAW_NOTICE =
11
+ "ADVANCED, NOT VISUAL — a raw-HTML page is not editable in Plexo's visual editor, so the owner can never tweak it themselves. Only use this when the owner explicitly asked for hand-written HTML; for any normal page or site use page_create_from_template instead. ";
12
+
13
+ export const DEPRECATED_TOOLS: Record<string, { replacement: string; raw?: boolean }> = {
14
+ create_landing_page: { replacement: "page_create_from_template" },
15
+ publish_landing_page: { replacement: "page_create_from_template + page_publish" },
16
+ update_template: { replacement: "page_describe + page_edit" },
17
+ create_landing_page_subpage: { replacement: "page_create_from_template (with siteId)" },
18
+ design_blog_layout: { replacement: "blog_layout_describe + blog_layout_edit" },
19
+ get_blog_layout: { replacement: "blog_layout_describe" },
20
+ create_raw_landing_page: { replacement: "page_create_from_template", raw: true },
21
+ publish_raw_landing_page: { replacement: "page_create_from_template + page_publish", raw: true },
22
+ update_raw_landing_page: { replacement: "page_describe + page_edit", raw: true },
23
+ };
24
+
25
+ export function markDeprecated<T extends { name: string; description?: string }>(tool: T): T {
26
+ const info = DEPRECATED_TOOLS[tool.name];
27
+ if (!info) return tool;
28
+ return { ...tool, description: `${DEPRECATED_PREFIX}${info.raw ? RAW_NOTICE : ""}${tool.description ?? ""}` };
29
+ }
30
+
31
+ /** Adds `deprecation` to a deprecated tool's successful JSON-text result (the plexo-web hosted tools add their own). */
32
+ export function addDeprecation<R extends { content?: Array<{ type: string; text?: string }>; isError?: boolean }>(name: string, response: R): R {
33
+ const info = DEPRECATED_TOOLS[name];
34
+ const first = response?.content?.[0];
35
+ if (!info || response.isError || !first || first.type !== "text" || typeof first.text !== "string") return response;
36
+ try {
37
+ const parsed = JSON.parse(first.text);
38
+ if (!parsed || typeof parsed !== "object" || Array.isArray(parsed) || parsed.deprecation) return response;
39
+ const withNotice = {
40
+ ...parsed,
41
+ deprecation: {
42
+ tool: name,
43
+ replacement: info.replacement,
44
+ removalAfterDays: DEPRECATION_WINDOW_DAYS,
45
+ message: `${name} still works for classic, email and raw-HTML pages but will be removed in ${DEPRECATION_WINDOW_DAYS} days. Use ${info.replacement} instead — pages built that way stay editable in Plexo's visual editor.`,
46
+ },
47
+ };
48
+ return { ...response, content: [{ ...first, text: JSON.stringify(withNotice, null, 2) }, ...response.content!.slice(1)] };
49
+ } catch {
50
+ return response;
51
+ }
52
+ }
package/src/index.ts CHANGED
@@ -14,6 +14,8 @@ import { DONATION_TOOL_DEFS, DONATION_TOOL_NAMES, handleDonationToolCall } from
14
14
  import { WP_MIGRATION_TOOL_DEFS, WP_MIGRATION_TOOL_NAMES, handleWpMigrationToolCall } from "./wpMigrationTools.js";
15
15
  import { FORM_TOOL_DEFS, FORM_TOOL_NAMES, handleFormToolCall } from "./formTools.js";
16
16
  import { APP_TOOL_DEFS, APP_TOOL_NAMES, callHostedAppTool } from "./appTools.js";
17
+ import { PAGE_TOOL_DEFS, PAGE_TOOL_NAMES, callHostedPageTool } from "./pageTools.js";
18
+ import { addDeprecation, markDeprecated } from "./deprecation.js";
17
19
 
18
20
  const server = new Server(
19
21
  {
@@ -658,12 +660,13 @@ To edit a page's CONTENT (designJson), use update_template with the same templat
658
660
  ...WP_MIGRATION_TOOL_DEFS,
659
661
  ...FORM_TOOL_DEFS,
660
662
  ...APP_TOOL_DEFS,
661
- ],
663
+ ...PAGE_TOOL_DEFS,
664
+ ].map(markDeprecated),
662
665
  };
663
666
  });
664
667
 
665
668
  // Implement tool handlers
666
- server.setRequestHandler(CallToolRequestSchema, async (request) => {
669
+ const handleToolCall = async (request: { params: { name: string; arguments?: unknown } }) => {
667
670
  const { name, arguments: args } = request.params;
668
671
  const client = new PlexoClient();
669
672
 
@@ -966,6 +969,9 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
966
969
  if (APP_TOOL_NAMES.has(name)) {
967
970
  return await callHostedAppTool(name, args);
968
971
  }
972
+ if (PAGE_TOOL_NAMES.has(name)) {
973
+ return await callHostedPageTool(name, args);
974
+ }
969
975
  for (const [names, handler] of [
970
976
  [DONATION_TOOL_NAMES, handleDonationToolCall],
971
977
  [WP_MIGRATION_TOOL_NAMES, handleWpMigrationToolCall],
@@ -992,7 +998,9 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
992
998
  isError: true,
993
999
  };
994
1000
  }
995
- });
1001
+ };
1002
+
1003
+ server.setRequestHandler(CallToolRequestSchema, async (request) => addDeprecation(request.params.name, (await handleToolCall(request)) as any));
996
1004
 
997
1005
  async function run() {
998
1006
  const transport = new StdioServerTransport();
@@ -0,0 +1,218 @@
1
+ // Mirrors plexo-web lib/mcp/pageTools.ts (the definitions only — every call is executed by
2
+ // plexo-web itself, see pageTools.ts). Regenerate when that file changes.
3
+ export const PAGE_TOOL_DEFS = [
4
+ {
5
+ "name": "page_describe",
6
+ "description": "START HERE for any landing page or site. Shows a site's pages (name, slug, address, whether each uses the new visual editor) and, for a visual (V2) page, its sections in order (id, kind, layout, a few words of what each says), the brand (colours, fonts, corners) and the catalog of everything you can add — every section kind with its layouts and fillable fields, the ready-made page templates (blank, home, landing, about, services, contact, pricing), and the blog, shop and funnel sections. Pass templateId (or siteId — the home page's id) and optionally slug to look at one of the site's other pages. Call it before page_edit, and again after edits if you need fresh section ids. Pass includeCatalog:false on later calls to keep the reply short. The workflow is: page_describe → page_edit with section commands → page_publish.",
7
+ "inputSchema": {
8
+ "type": "object",
9
+ "properties": {
10
+ "templateId": {
11
+ "type": "string",
12
+ "description": "A page's id — or the site's home page id to see the whole site."
13
+ },
14
+ "siteId": {
15
+ "type": "string",
16
+ "description": "The site's home page id (same as templateId; use whichever you have)."
17
+ },
18
+ "slug": {
19
+ "type": "string",
20
+ "description": "Optional: a page of the site by its address segment, e.g. \"about\", when templateId/siteId is the site's home page."
21
+ },
22
+ "includeCatalog": {
23
+ "type": "boolean",
24
+ "description": "Default true. Pass false once you already know the catalog."
25
+ }
26
+ }
27
+ }
28
+ },
29
+ {
30
+ "name": "page_edit",
31
+ "description": "Changes a visual page section by section — the way to edit any page made with page_create_from_template (and any page the owner designed in the visual editor). Saves it as the page's working copy in the editor (exactly what the editor's own autosave does); nothing goes live until page_publish. Each command is one of: {op:\"addSection\", kind, variant?, content?, style?, afterSectionId? | index?} · {op:\"updateSection\", sectionId, content?, variant?, style?} · {op:\"removeSection\", sectionId} · {op:\"moveSection\", sectionId, index? | afterSectionId?} · {op:\"duplicateSection\", sectionId} · {op:\"setBrand\", tokens:{primaryColor?, secondaryColor?, headingFont?, bodyFont?, neutrals? (cool|warm|dark), roundness? (sharp|soft|round)}} · {op:\"renamePage\", name}. kind/variant and the content field paths (\"headline\", \"items.0.title\") come from the catalog in page_describe; a list field needs the whole list; style is {background? (canvas|surface|sunken|primary|inverted|gradient|image), align? (left|center), spacing? (tight|normal|airy)}. sectionId values come from page_describe and are only valid for that page. Write real, specific copy for the business — never lorem ipsum. Each command is checked on its own: good ones are saved, bad ones come back with a plain-English reason, so read the results and resend only the ones that failed. Up to 40 commands per call. To add a whole new page to the site use page_create_from_template with siteId — an addPage command here is declined with that hint. Pages built with the classic tools (create_landing_page etc.) or as raw HTML can't be edited with this.",
32
+ "inputSchema": {
33
+ "type": "object",
34
+ "properties": {
35
+ "templateId": {
36
+ "type": "string",
37
+ "description": "The page's templateId (from page_create_from_template, list_landing_pages or get_landing_page_pages). For a site's home page this is also the siteId."
38
+ },
39
+ "slug": {
40
+ "type": "string",
41
+ "description": "Optional: edit the site's page with this address segment instead of templateId's own page."
42
+ },
43
+ "commands": {
44
+ "type": "array",
45
+ "maxItems": 40,
46
+ "items": {
47
+ "type": "object",
48
+ "properties": {
49
+ "op": {
50
+ "type": "string"
51
+ }
52
+ },
53
+ "required": [
54
+ "op"
55
+ ],
56
+ "additionalProperties": true
57
+ }
58
+ }
59
+ },
60
+ "required": [
61
+ "templateId",
62
+ "commands"
63
+ ]
64
+ }
65
+ },
66
+ {
67
+ "name": "page_create_from_template",
68
+ "description": "Creates a visual page that is already complete: header, sections and footer all filled in with starting wording. Without siteId it starts a NEW SITE (this is its home page); with siteId it adds a page to that site (Ultra plan). templateId is a page template: blank, home, landing, about, services, contact or pricing (home for a first page, landing for a one-page sales site). Pass content — the same commands as page_edit — to personalise it in the same call (headline, copy, brand colours with setBrand), so the owner sees a finished page for their business straight away; any wording you don't change stays as the template's sample text, so replace the key copy. It isn't published: call page_publish with a domain when the owner is ready. Never ask the owner for a name or address first — name the page yourself from what it's about.",
69
+ "inputSchema": {
70
+ "type": "object",
71
+ "properties": {
72
+ "name": {
73
+ "type": "string",
74
+ "description": "Page name, e.g. \"Home\", \"Pricing\" or the business's name for a new site."
75
+ },
76
+ "templateId": {
77
+ "type": "string",
78
+ "enum": [
79
+ "blank",
80
+ "home",
81
+ "landing",
82
+ "about",
83
+ "services",
84
+ "contact",
85
+ "pricing"
86
+ ],
87
+ "description": "Which ready-made page to start from. Default home."
88
+ },
89
+ "siteId": {
90
+ "type": "string",
91
+ "description": "Add the page to this existing visual site (its home page id). Omit to start a new site."
92
+ },
93
+ "content": {
94
+ "type": "array",
95
+ "maxItems": 40,
96
+ "items": {
97
+ "type": "object",
98
+ "properties": {
99
+ "op": {
100
+ "type": "string"
101
+ }
102
+ },
103
+ "required": [
104
+ "op"
105
+ ],
106
+ "additionalProperties": true
107
+ },
108
+ "description": "Optional page_edit commands applied right after creating the page. Section ids don't exist yet, so use addSection / setBrand, or call page_describe first to get ids for updateSection."
109
+ }
110
+ },
111
+ "required": [
112
+ "name"
113
+ ]
114
+ }
115
+ },
116
+ {
117
+ "name": "page_publish",
118
+ "description": "Puts a visual page's latest changes live (and keeps the previous version in its history). For a site's home page, also pass domain to give it an address: a short subdomain like \"careconnect\" (becomes careconnect.<pages domain>) or the owner's own domain. Other pages of the site go live at that same address automatically (e.g. /about) once the home page has a domain — publish them too so their latest edits are live. If the home page has no address yet and none is given, the reply lists suggestedDomains to offer the owner. Free plans publish only the home page on a Plexo address and one live site; the reply says plainly when a limit applies.",
119
+ "inputSchema": {
120
+ "type": "object",
121
+ "properties": {
122
+ "templateId": {
123
+ "type": "string",
124
+ "description": "The page's templateId (from page_create_from_template, list_landing_pages or get_landing_page_pages). For a site's home page this is also the siteId."
125
+ },
126
+ "domain": {
127
+ "type": "string",
128
+ "description": "Home page only. Subdomain slug (e.g. 'kicks') or custom domain ('kicks.com')."
129
+ },
130
+ "type": {
131
+ "type": "string",
132
+ "enum": [
133
+ "SUBDOMAIN",
134
+ "CUSTOM"
135
+ ],
136
+ "description": "Inferred from the domain string if omitted."
137
+ }
138
+ },
139
+ "required": [
140
+ "templateId"
141
+ ]
142
+ }
143
+ },
144
+ {
145
+ "name": "blog_layout_describe",
146
+ "description": "Shows a blog's custom post page or listing (index) page layout built with the visual editor: its sections, the brand and the catalog (the blogArticle section is the post body, blogList the list of posts). If the blog has no custom layout yet it says so and what blog_layout_edit will start from. Use before blog_layout_edit.",
147
+ "inputSchema": {
148
+ "type": "object",
149
+ "properties": {
150
+ "templateId": {
151
+ "type": "string",
152
+ "description": "The blog site's home page id."
153
+ },
154
+ "kind": {
155
+ "type": "string",
156
+ "enum": [
157
+ "post",
158
+ "listing"
159
+ ],
160
+ "description": "post = a single article's page; listing = the blog index."
161
+ },
162
+ "includeCatalog": {
163
+ "type": "boolean",
164
+ "description": "Default true. Pass false once you know the catalog."
165
+ }
166
+ },
167
+ "required": [
168
+ "templateId",
169
+ "kind"
170
+ ]
171
+ }
172
+ },
173
+ {
174
+ "name": "blog_layout_edit",
175
+ "description": "Designs a blog's post page or listing page with the visual editor, using the same section commands as page_edit. Creates the layout the first time (an empty page you fill with commands). A post layout needs a blogArticle section and a listing layout needs a blogList section — until it has one the blog falls back to the default theme, and the reply warns about it. Typical post layout: header, blogArticle, cta, footer. Takes effect immediately (blog layouts have no separate publish step). Each command is one of: {op:\"addSection\", kind, variant?, content?, style?, afterSectionId? | index?} · {op:\"updateSection\", sectionId, content?, variant?, style?} · {op:\"removeSection\", sectionId} · {op:\"moveSection\", sectionId, index? | afterSectionId?} · {op:\"duplicateSection\", sectionId} · {op:\"setBrand\", tokens:{primaryColor?, secondaryColor?, headingFont?, bodyFont?, neutrals? (cool|warm|dark), roundness? (sharp|soft|round)}} · {op:\"renamePage\", name}. kind/variant and the content field paths (\"headline\", \"items.0.title\") come from the catalog in page_describe; a list field needs the whole list; style is {background? (canvas|surface|sunken|primary|inverted|gradient|image), align? (left|center), spacing? (tight|normal|airy)}. sectionId values come from page_describe and are only valid for that page. Write real, specific copy for the business — never lorem ipsum. Each command is checked on its own: good ones are saved, bad ones come back with a plain-English reason, so read the results and resend only the ones that failed.",
176
+ "inputSchema": {
177
+ "type": "object",
178
+ "properties": {
179
+ "templateId": {
180
+ "type": "string",
181
+ "description": "The blog site's home page id."
182
+ },
183
+ "kind": {
184
+ "type": "string",
185
+ "enum": [
186
+ "post",
187
+ "listing"
188
+ ]
189
+ },
190
+ "commands": {
191
+ "type": "array",
192
+ "maxItems": 40,
193
+ "items": {
194
+ "type": "object",
195
+ "properties": {
196
+ "op": {
197
+ "type": "string"
198
+ }
199
+ },
200
+ "required": [
201
+ "op"
202
+ ],
203
+ "additionalProperties": true
204
+ }
205
+ },
206
+ "startFresh": {
207
+ "type": "boolean",
208
+ "description": "Only if the blog's current layout was built in the classic editor and has content: true replaces it. Ask the owner first."
209
+ }
210
+ },
211
+ "required": [
212
+ "templateId",
213
+ "kind",
214
+ "commands"
215
+ ]
216
+ }
217
+ }
218
+ ];
@@ -0,0 +1,12 @@
1
+ import { PAGE_TOOL_DEFS } from "./pageToolDefs.js";
2
+ import { callHostedAppTool } from "./appTools.js";
3
+
4
+ // Visual pages and sites (page_describe, page_edit, page_create_from_template, page_publish,
5
+ // blog_layout_describe, blog_layout_edit). Like the app tools they aren't reimplemented here:
6
+ // each call is forwarded to plexo-web's hosted MCP endpoint, which runs the same code SOL uses,
7
+ // so an assistant gets identical results in the dashboard and in Claude Desktop / Cursor.
8
+
9
+ export { PAGE_TOOL_DEFS };
10
+ export const PAGE_TOOL_NAMES = new Set(PAGE_TOOL_DEFS.map((t) => t.name));
11
+
12
+ export const callHostedPageTool = callHostedAppTool;