@prenta/mcp-server 0.23.0

package/README.md

@@ -0,0 +1,130 @@
+# @prenta/mcp-server
+
+A [Model Context Protocol](https://modelcontextprotocol.io) server that lets AI agents (Claude, Cursor, ChatGPT, etc.) read and write content in your Prenta CMS.
+
+## Install & connect
+
+You don't need to install this globally — your MCP client will run it via `npx`.
+
+**Cursor / Claude Desktop:**
+
+```json
+{
+  "mcpServers": {
+    "prenta": {
+      "command": "npx",
+      "args": ["-y", "@prenta/mcp-server"],
+      "env": {
+        "PRENTA_BASE_URL": "https://your-site.com",
+        "PRENTA_API_KEY": "act_sk_..."
+      }
+    }
+  }
+}
+```
+
+Generate an `PRENTA_API_KEY` from your CMS admin under **API Keys → New API Key**. Grant it the scopes the agent needs (e.g. content + media + pageBuilder).
+
+## Tools exposed
+
+| Tool                           | What it does                                         |
+| ------------------------------ | ---------------------------------------------------- |
+| `list_collections`             | Discover available collections and their fields      |
+| `list_documents`               | Paginated list of documents in a collection          |
+| `get_document`                 | Fetch a document by ID                               |
+| `create_document`              | Create a new document with explicit fields (DRAFT)   |
+| `update_document`              | Patch an existing document                           |
+| `delete_document`              | Soft-delete a document                               |
+| `get_global` / `update_global` | Read/update globals (site settings, etc.)            |
+| `list_media`                   | Browse the media library                             |
+| `generate_page`                | AI page-builder: prompt → page tree (no persistence) |
+| `create_page_from_prompt`      | One-shot: prompt → tree → persisted page document    |
+| `generate_block`               | AI generate a single page-builder block              |
+| `resolve_url`                  | Map a public URL path to its CMS document            |
+
+### AI content authoring (any non-page collection)
+
+The agent can also author structured content for blog posts, case studies, services, locations, team profiles, FAQs, testimonials — any collection that isn't a page builder. Each tool maps a free-form prompt onto the collection's field schema and persists the result.
+
+| Tool                   | Default collection | Notes                                                                                               |
+| ---------------------- | ------------------ | --------------------------------------------------------------------------------------------------- |
+| `create_in_collection` | _(required arg)_   | Generic. Pass `template: service \| location \| team_member` for built-in prompt-enrichment recipes |
+| `create_blog_post`     | `posts`            | Blog post sugar                                                                                     |
+| `create_case_study`    | `case-studies`     | Plus `clientName` / `industry` hints                                                                |
+
+All authoring tools share the same base inputs (`prompt`, `tone`, `targetAudience`, `context`, `title`, `slug`, `publish`) and accept a `collection` override when your site uses non-conventional slugs.
+
+> The standalone `create_service` / `create_location` / `create_team_member` tools were collapsed into `create_in_collection`. Use `create_in_collection({ template: "service" | "location" | "team_member", ... })` instead.
+
+### Building pages section-by-section
+
+Pages are authored as an ordered list of sections (the same model the visual Page Editor reads/writes), so an agent can build a real, previewable, editable page rather than disposable HTML.
+
+| Tool                                            | What it does                                            |
+| ----------------------------------------------- | ------------------------------------------------------- |
+| `list_section_types` / `get_section_schema`     | Discover registered section types + their field schema  |
+| `validate_section_content`                      | Validate content against a type schema (no persistence) |
+| `list_page_sections`                            | List a page's ordered sections                          |
+| `add_page_section` / `update_page_section`      | Add or patch a single section in place                  |
+| `reorder_page_sections` / `remove_page_section` | Reorder / remove a section                              |
+| `toggle_page_section_visibility`                | Show or hide a section without deleting it              |
+
+### Resolving relationships
+
+Relationship fields store a **target document ID**, but prompts speak in slugs ("set the author to jane-doe"). These tools let an agent resolve them instead of guessing IDs.
+
+| Tool                        | What it does                                                                        |
+| --------------------------- | ----------------------------------------------------------------------------------- |
+| `get_relationship_fields`   | List a collection's relationship/media/select fields + each field's `relationTo`    |
+| `resolve_relationship`      | Resolve an exact slug → `{ id, slug, title, status }` within a collection           |
+| `list_relationship_targets` | Browse candidate documents (`{ id, slug, title, status }`) when the slug is unknown |
+
+Typical flow: `get_relationship_fields(collection)` → find the field's `relationTo` → `resolve_relationship(relationTo, slug)` → `update_document` with the returned ID.
+
+### Navigation menus
+
+Menus live in the `navigations` collection (link tree on `data.items`). These tools wrap the document API with tree-aware conveniences so an agent builds a real, editable menu — and can wire a published page into one without hand-deriving its URL.
+
+| Tool                                                            | What it does                                                                                                     |
+| --------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| `list_navigations` / `get_navigation`                           | List menus (`{ id, name, slug, location, itemCount }`) or read one + its tree                                    |
+| `create_navigation` / `update_navigation` / `delete_navigation` | Create, edit metadata / replace tree, or soft-delete a menu                                                      |
+| `add_navigation_item`                                           | Add a link — explicit `{ label, url }` or a `page` ref ("link page X into menu Y"); optional `parentId` nests it |
+| `remove_navigation_item` / `reorder_navigation_items`           | Remove one item (+ sub-tree), or reorder one level by id permutation                                             |
+| `validate_navigation_tree`                                      | Validate a menu or candidate `items` (no save): `{ valid, errors, warnings, stats }`                             |
+
+### Forms
+
+The agent can author forms and manage the submissions inbox end-to-end (write-role API key required).
+
+| Tool                                                                         | What it does                                                              |
+| ---------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
+| `list_forms` / `get_form`                                                    | Discover form definitions and read one                                    |
+| `create_form` / `update_form` / `delete_form`                                | Create, edit metadata, or delete a form                                   |
+| `duplicate_form`                                                             | Copy a form into a new draft                                              |
+| `get_form_schema` / `save_form_schema`                                       | Read or replace the (versioned) field schema                              |
+| `list_form_submissions` / `list_form_entries` / `get_form_entry`             | Read submissions (PII-sensitive; explicit `formId` required)              |
+| `set_form_entry_status` / `bulk_set_form_entry_status` / `delete_form_entry` | Manage inbox state (read/star/archive) and delete entries                 |
+| `export_form_entries`                                                        | Export all submissions as CSV (bulk PII egress; requires `confirm: true`) |
+
+## Scoping
+
+The agent inherits whatever scopes you grant to its API key. Use the **Content** preset to allow read/create/update across all collections without admin powers. Use **Custom** to lock down to specific collections.
+
+## Direct (non-MCP) use
+
+You can also import the underlying `PrentaClient` programmatically:
+
+```ts
+import { PrentaClient } from '@prenta/mcp-server'
+
+const cms = new PrentaClient({
+  baseUrl: 'https://your-site.com',
+  apiKey: process.env.PRENTA_API_KEY!,
+})
+
+const page = await cms.createPageFromPrompt({
+  prompt: 'A landing page for a New York City house cleaning service',
+  publish: false,
+})
+```

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}

package/dist/cli.js

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+/**
+ * stdio entrypoint for the Prenta CMS MCP server. Wire this into your AI
+ * tool's MCP config:
+ *
+ *   {
+ *     "mcpServers": {
+ *       "prenta": {
+ *         "command": "npx",
+ *         "args": ["-y", "@prenta/mcp-server"],
+ *         "env": {
+ *           "PRENTA_BASE_URL": "https://your-site.com",
+ *           "PRENTA_API_KEY": "act_sk_..."
+ *         }
+ *       }
+ *     }
+ *   }
+ */
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { createPrentaMcpServer } from './server.js';
+async function main() {
+    const baseUrl = process.env.PRENTA_BASE_URL;
+    const apiKey = process.env.PRENTA_API_KEY;
+    if (!baseUrl) {
+        console.error('PRENTA_BASE_URL environment variable is required');
+        process.exit(1);
+    }
+    if (!apiKey) {
+        console.error('PRENTA_API_KEY environment variable is required (act_sk_... from /api-keys)');
+        process.exit(1);
+    }
+    if (!apiKey.startsWith('act_sk_')) {
+        console.error('PRENTA_API_KEY does not look like an Prenta API key (expected act_sk_ prefix)');
+        process.exit(1);
+    }
+    const { server } = createPrentaMcpServer({ baseUrl, apiKey });
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((err) => {
+    console.error('[prenta-mcp] fatal:', err);
+    process.exit(1);
+});
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAA;AAChF,OAAO,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAA;AAEnD,KAAK,UAAU,IAAI;IACjB,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,eAAe,CAAA;IAC3C,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,cAAc,CAAA;IAEzC,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,OAAO,CAAC,KAAK,CAAC,kDAAkD,CAAC,CAAA;QACjE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;IACjB,CAAC;IACD,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,OAAO,CAAC,KAAK,CAAC,6EAA6E,CAAC,CAAA;QAC5F,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;IACjB,CAAC;IACD,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;QAClC,OAAO,CAAC,KAAK,CAAC,+EAA+E,CAAC,CAAA;QAC9F,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;IACjB,CAAC;IAED,MAAM,EAAE,MAAM,EAAE,GAAG,qBAAqB,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,CAAA;IAC7D,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAA;IAC5C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAA;AACjC,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;IACnB,OAAO,CAAC,KAAK,CAAC,qBAAqB,EAAE,GAAG,CAAC,CAAA;IACzC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;AACjB,CAAC,CAAC,CAAA"}