@content-island/mcp 0.1.13 → 0.2.1

package/README.md

@@ -12,6 +12,25 @@ A Model Context Protocol (MCP) server that enables seamless integration between
 - **Type-safe integration**. Generate TypeScript types from your Content Island content models.
 - **Zero-config setup**. Streamlined project initialization with pre-configured build tools and settings.
 - **LLM-optimized workflow**. Purpose-built for AI-assisted development with clear, structured commands.
+- **Content authoring**. Create content entries and upload media files directly from your LLM.
+
+### Available Tools
+
+| Tool                                | Description                                                              | Token required    |
+| ----------------------------------- | ------------------------------------------------------------------------ | ----------------- |
+| `get-content-island-project`        | Get project details (languages, content types, fields)                   | Read **or** Write |
+| `list-content-island-contents`      | List content entries with filters, sort and pagination (returns hasMore) | Read **or** Write |
+| `create-content-island-content`     | Create a new content entry with fields per language                      | **Write**         |
+| `update-content-island-field-value` | Update or insert a field value identified by `(fieldName, language)`     | **Write**         |
+| `publish-content-island-content`    | Promote a content's current draft to the live state (preflight-gated)    | **Write**         |
+| `upload-content-island-media`       | Upload a media file from a local path or URL                             | **Write**         |
+
+> **Note**: A **read token** is sufficient for read-only tools. Tools that create or upload data require a **write token**. A write token also works for read-only tools.
+
+### Behavior notes
+
+- The MCP server always reads in **preview mode**, so drafts and unpublished field values are visible. The configured access token is automatically prefixed with `PREVIEW_` before it reaches the API. This keeps reads and writes consistent: the tools `create-content-island-content` and `update-content-island-field-value` write to the working state, and `list-content-island-contents` / `get-content-island-project` read from that same working state.
+- `publish-content-island-content` runs a **server-side preflight** before publishing and refuses the call when the content is not valid: every `isRequired` field must have a non-empty value in every project language, and populated values must satisfy their `min-length`, `max-length` and `media-type` validations. `unique` is enforced by the backend. If the preflight fails, the response lists every problem in one pass so the caller can fix them via `update-content-island-field-value` and retry.
 
 ### Requirements
 
@@ -136,9 +155,9 @@ Follow the MCP install [guide](https://modelcontextprotocol.io/quickstart/user),
 
 You can configure the MCP server using environment variables. The following variables are available:
 
-| name                             | required | description                                                                                                                          |
-| -------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------ |
-| `CONTENT_ISLAND_ACCESS_TOKEN`    | `true`   | Your project’s `access token`.<br/>You can find this token in the [General tab](https://docs.contentisland.net/ui/project/general/). |
-| `CONTENT_ISLAND_DOMAIN`          | `false`  | Domain used for requests. Useful if you're using Content Island `On Premise`.<br/>Default: `api.contentisland.net`                   |
-| `CONTENT_ISLAND_SECURE_PROTOCOL` | `false`  | Whether to use HTTPS for requests.<br/>Default: `true` (use HTTPS)                                                                   |
-| `CONTENT_ISLAND_API_VERSION`     | `false`  | Version of the [REST API](https://docs.contentisland.net/rest-api/v1/overview/).<br/>Default: `1.0`                                  |
+| name                             | required | description                                                                                                                                                                                                                                                                                              |
+| -------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `CONTENT_ISLAND_ACCESS_TOKEN`    | `true`   | Your project’s access token. A **read token** is sufficient for `get-content-island-project`. A **write token** is required for `create-content-island-content` and `upload-content-island-media`.<br/>You can find this token in the [General tab](https://docs.contentisland.net/ui/project/general/). |
+| `CONTENT_ISLAND_DOMAIN`          | `false`  | Domain used for requests. Useful if you're using Content Island `On Premise`.<br/>Default: `api.contentisland.net`                                                                                                                                                                                       |
+| `CONTENT_ISLAND_SECURE_PROTOCOL` | `false`  | Whether to use HTTPS for requests.<br/>Default: `true` (use HTTPS)                                                                                                                                                                                                                                       |
+| `CONTENT_ISLAND_API_VERSION`     | `false`  | Version of the [REST API](https://docs.contentisland.net/rest-api/v1/overview/).<br/>Default: `1.0`                                                                                                                                                                                                      |

package/dist/index.js

@@ -1,31 +1,38 @@
-import { z as o } from "zod";
-import { McpServer as l } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { createClient as p } from "@content-island/api-client";
-import { StdioServerTransport as d } from "@modelcontextprotocol/sdk/server/stdio.js";
-const r = {
+import { z as i } from "zod";
+import { McpServer as w } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { createClient as v } from "@content-island/api-client";
+import { readFile as S } from "node:fs/promises";
+import { basename as A, extname as R } from "node:path";
+import { StdioServerTransport as O } from "@modelcontextprotocol/sdk/server/stdio.js";
+const f = {
   CONTENT_ISLAND_ACCESS_TOKEN: process.env.CONTENT_ISLAND_ACCESS_TOKEN,
   CONTENT_ISLAND_DOMAIN: process.env.CONTENT_ISLAND_DOMAIN,
   CONTENT_ISLAND_SECURE_PROTOCOL: process.env.CONTENT_ISLAND_SECURE_PROTOCOL !== "false",
   CONTENT_ISLAND_API_VERSION: process.env.CONTENT_ISLAND_API_VERSION
-}, u = "0.1.13", g = {
-  version: u
-}, s = new l({
+}, I = "PREVIEW_", x = (e) => e.startsWith(I) ? e : `${I}${e}`, g = () => v({
+  accessToken: x(f.CONTENT_ISLAND_ACCESS_TOKEN),
+  domain: f.CONTENT_ISLAND_DOMAIN,
+  secureProtocol: f.CONTENT_ISLAND_SECURE_PROTOCOL,
+  apiVersion: f.CONTENT_ISLAND_API_VERSION
+}), L = "0.2.1", k = {
+  version: L
+}, u = new w({
   name: "Content Island",
-  version: g.version
-}), m = () => {
-  s.prompt(
+  version: k.version
+}), j = () => {
+  u.prompt(
     "create-content-island-project",
     "Professional MCP Server prompt for creating modern frontend projects integrated with Content Island CMS",
     {
-      framework: o.string().describe("Framework choice (Next.js, Astro, Nuxt, etc.)"),
-      pages: o.string().describe("Pages needed (Homepage, Blog, Contact, etc.)"),
-      location: o.string().describe("Project location (root directory or subfolder name)"),
-      styling: o.string().describe("Styling preference (Tailwind CSS or custom)"),
-      design: o.string().describe("Design assets (mockups, wireframes, or none)")
+      framework: i.string().describe("Framework choice (Next.js, Astro, Nuxt, etc.)"),
+      pages: i.string().describe("Pages needed (Homepage, Blog, Contact, etc.)"),
+      location: i.string().describe("Project location (root directory or subfolder name)"),
+      styling: i.string().describe("Styling preference (Tailwind CSS or custom)"),
+      design: i.string().describe("Design assets (mockups, wireframes, or none)")
     },
-    async (c) => {
-      const { framework: e, pages: i, location: t, styling: n, design: a } = c;
-      return e && i && t && n && a ? {
+    async (e) => {
+      const { framework: t, pages: a, location: n, styling: o, design: s } = e;
+      return t && a && n && o && s ? {
         description: "Content Island project generator",
         messages: [
           {
@@ -34,24 +41,24 @@ const r = {
               type: "text",
               text: `# Content Island Website Generator
 
-I'll create a professional ${e} application integrated with your Content Island project.
+I'll create a professional ${t} application integrated with your Content Island project.
 
 **Configuration:**
-- Framework: **${e}**
-- Pages: ${i}
-- Location: ${t}
-- Styling: ${n}
-- Design: ${a}
+- Framework: **${t}**
+- Pages: ${a}
+- Location: ${n}
+- Styling: ${o}
+- Design: ${s}
 
 # CRITICAL IMPLEMENTATION INSTRUCTIONS - FOLLOW EXACTLY
 
-You are a specialized web development assistant creating a ${e} application integrated with Content Island CMS. You MUST follow these instructions PRECISELY without any deviation or interpretation.
+You are a specialized web development assistant creating a ${t} application integrated with Content Island CMS. You MUST follow these instructions PRECISELY without any deviation or interpretation.
 
 ## MANDATORY EXECUTION SEQUENCE - NO EXCEPTIONS
 
 ### STEP 1: FRAMEWORK PROJECT INITIALIZATION (REQUIRED FIRST ACTION)
 - FIRST execute the appropriate framework CLI command to create the base project:
-${e === "Next.js" ? `  * Run: npx create-next-app@latest ${t !== "root directory" ? t : "."} --typescript --tailwind --eslint --app --src-dir --import-alias "@/*"` : e === "Nuxt" ? `  * Run: npx nuxi@latest init ${t !== "root directory" ? t : "."}` : e === "Astro" ? `  * Run: npm create astro@latest ${t !== "root directory" ? t : "."}` : e === "SvelteKit" ? `  * Run: npm create svelte@latest ${t !== "root directory" ? t : "."}` : e === "Vite" ? `  * Run: npm create vite@latest ${t !== "root directory" ? t : "."} -- --template react-ts` : `  * Run the appropriate CLI command for ${e} to create a new project in ${t !== "root directory" ? t : "current directory"}`}
+${t === "Next.js" ? `  * Run: npx create-next-app@latest ${n !== "root directory" ? n : "."} --typescript --tailwind --eslint --app --src-dir --import-alias "@/*"` : t === "Nuxt" ? `  * Run: npx nuxi@latest init ${n !== "root directory" ? n : "."}` : t === "Astro" ? `  * Run: npm create astro@latest ${n !== "root directory" ? n : "."}` : t === "SvelteKit" ? `  * Run: npm create svelte@latest ${n !== "root directory" ? n : "."}` : t === "Vite" ? `  * Run: npm create vite@latest ${n !== "root directory" ? n : "."} -- --template react-ts` : `  * Run the appropriate CLI command for ${t} to create a new project in ${n !== "root directory" ? n : "current directory"}`}
 - Navigate to the project directory if created in a subfolder
 - Wait for the framework setup to complete before proceeding
 - DO NOT skip this step - the framework base is required for all subsequent steps
@@ -63,7 +70,7 @@ ${e === "Next.js" ? `  * Run: npx create-next-app@latest ${t !== "root directory
 - If the tool fails, STOP and ask user to check their Content Island configuration
 
 ### STEP 3: PACKAGE INSTALLATION (MANDATORY BEFORE CODE GENERATION)
-${e === "Nuxt" ? `
+${t === "Nuxt" ? `
 - FIRST install the official Content Island packages:
   * npm install @content-island/nuxt@latest
   * npm install @content-island/api-client@latest
@@ -97,7 +104,7 @@ ${e === "Nuxt" ? `
   Result: title: string;
 
 ### STEP 5: API CLIENT IMPLEMENTATION (DOCUMENTED METHODS ONLY)
-${e === "Nuxt" ? `
+${t === "Nuxt" ? `
 - Use Nuxt Content Island composables from '@content-island/nuxt'
 - Configure the module in nuxt.config.ts with your project settings
 - Check Nuxt/Content Island documentation for setup: https://github.com/content-island/nuxt-content-island#readme
@@ -132,28 +139,28 @@ ${e === "Nuxt" ? `
 
 
 ### STEP 6: PROJECT STRUCTURE GENERATION (FRAMEWORK-SPECIFIC)
-- Framework: ${e}
-- Location: ${t}
-- Pages requested: ${i}
-- Styling: ${n}
-- Design approach: ${a}
+- Framework: ${t}
+- Location: ${n}
+- Pages requested: ${a}
+- Styling: ${o}
+- Design approach: ${s}
 
 #### FRAMEWORK-SPECIFIC REQUIREMENTS:
-${e === "Next.js" ? `
+${t === "Next.js" ? `
 - Use App Router (app/ directory)
 - Implement getStaticProps/getServerSideProps for data fetching
 - Create proper page.tsx files for each route
 - Use Next.js Image component for optimization
 - Implement proper metadata for SEO
 ` : ""}
-${e === "Astro" ? `
+${t === "Astro" ? `
 - Use .astro components with proper frontmatter
 - Implement getStaticPaths for dynamic routes
 - Use partial hydration with client:load directives
 - Create Layout components for consistent structure
 - Use Astro.glob() for content collection if needed
 ` : ""}
-${e === "Nuxt" ? `
+${t === "Nuxt" ? `
 - Use Nuxt 3 composition API
 - Implement useFetch for data fetching
 - Create proper pages/ directory structure
@@ -162,7 +169,7 @@ ${e === "Nuxt" ? `
 ` : ""}
 
 ### STEP 7: ENVIRONMENT CONFIGURATION (MANDATORY FILES)
-${e === "Nuxt" ? `
+${t === "Nuxt" ? `
 - Configure Content Island in nuxt.config.ts:
   runtimeConfig: {
     contentIsland: {
@@ -177,14 +184,14 @@ ${e === "Nuxt" ? `
 - Document environment setup in README.md
 
 ### STEP 8: STYLING IMPLEMENTATION
-${n.toLowerCase().includes("tailwind") ? `
-- Install and configure Tailwind CSS according to ${e} official documentation
+${o.toLowerCase().includes("tailwind") ? `
+- Install and configure Tailwind CSS according to ${t} official documentation
 - Create tailwind.config.js with proper content paths
 - Add Tailwind directives to main CSS file
 - Implement responsive design classes (sm:, md:, lg:, xl:)
 - Use Tailwind accessibility classes for WCAG compliance
 ` : `
-- Implement ${n} according to ${e} best practices
+- Implement ${o} according to ${t} best practices
 - Create modular CSS structure
 - Implement responsive design with media queries
 - Ensure accessibility with proper contrast and focus states
@@ -242,7 +249,7 @@ ${n.toLowerCase().includes("tailwind") ? `
 1. NEVER invent Content Island API methods not documented
 2. NEVER create example/dummy interfaces - use ONLY project structure data
 3. NEVER proceed without executing framework CLI first and calling get-content-island-project tool second
-4. NEVER skip installing the correct Content Island packages (${e === "Nuxt" ? "@content-island/nuxt@latest and @content-island/api-client@latest" : "@content-island/api-client@latest"})
+4. NEVER skip installing the correct Content Island packages (${t === "Nuxt" ? "@content-island/nuxt@latest and @content-island/api-client@latest" : "@content-island/api-client@latest"})
 5. NEVER skip error handling implementation
 6. NEVER ignore accessibility requirements
 7. NEVER use deprecated framework patterns
@@ -255,7 +262,7 @@ ${n.toLowerCase().includes("tailwind") ? `
 ## VALIDATION CHECKLIST - VERIFY BEFORE COMPLETION:
 □ Framework CLI executed to create base project structure
 □ get-content-island-project tool called and data parsed
-${e === "Nuxt" ? `
+${t === "Nuxt" ? `
 □ @content-island/nuxt@latest and @content-island/api-client@latest installed
 □ @content-island/nuxt configured in nuxt.config.ts modules
 □ Media type imported from '@content-island/api-client' when needed
@@ -266,7 +273,7 @@ ${e === "Nuxt" ? `
 □ All content types have corresponding API functions using official client
 `}
 □ TypeScript interfaces exactly match project structure
-□ All requested pages (${i}) are implemented
+□ All requested pages (${a}) are implemented
 □ Error handling implemented for all API calls
 □ Loading states implemented for all data fetching
 □ Responsive design implemented
@@ -312,24 +319,425 @@ Please provide all this information so I can create your project.`
       };
     }
   );
-}, E = () => {
-  m();
-}, f = () => {
-  s.tool("get-content-island-project", "Get the user's Content Island project details", async () => {
-    const e = await p({
-      accessToken: r.CONTENT_ISLAND_ACCESS_TOKEN,
-      domain: r.CONTENT_ISLAND_DOMAIN,
-      secureProtocol: r.CONTENT_ISLAND_SECURE_PROTOCOL,
-      apiVersion: r.CONTENT_ISLAND_API_VERSION
-    }).getProject();
+}, P = () => {
+  j();
+}, U = {
+  401: "Invalid or expired token. Check your CONTENT_ISLAND_ACCESS_TOKEN configuration.",
+  403: "This token does not have write permissions. Configure a write token in CONTENT_ISLAND_ACCESS_TOKEN.",
+  404: "Resource not found. Verify that the content type, content ID, or project exists."
+}, M = (e) => {
+  const t = U[e.status] ?? `API error: ${e.status} ${e.statusText}`;
+  if (!e.body)
+    return t;
+  const a = [];
+  if (e.body.error && a.push(e.body.error), e.body.fieldErrors)
+    for (const [n, o] of Object.entries(e.body.fieldErrors)) {
+      const s = typeof o == "string" ? o : JSON.stringify(o);
+      a.push(`  - ${n}: ${s}`);
+    }
+  return a.length > 0 ? `${t}
+${a.join(`
+`)}` : t;
+}, h = (e) => {
+  let t = e instanceof Error ? e.message : String(e);
+  try {
+    const a = JSON.parse(t);
+    t = M(a);
+  } catch {
+  }
+  return { content: [{ type: "text", text: t }], isError: !0 };
+}, F = () => {
+  u.tool(
+    "create-content-island-content",
+    `Create a new content entry in the Content Island project. Requires a write token.
+
+WORKFLOW (perform BEFORE calling this tool):
+1. Call get-content-island-project to fetch the project schema. Identify the contentType and read every field's "type", "isArray", "validations" array ({ name, customArgs? }), and the project's "languages" list.
+2. For every field you plan to set, validate the value against the field's "validations":
+   - "required": every required field must be present and non-empty.
+   - "min-length" / "max-length": value.length (or array length when isArray) must satisfy customArgs.
+   - "unique": warn the user that the API will reject duplicates against existing contents of this type.
+   - "media-type": only file extensions listed in customArgs are allowed.
+   If any constraint would fail, do NOT call this tool — ask the user for a valid value first.
+3. Language coverage:
+   - If project.languages has more than one language and the user provided field values for only one language (or omitted "content"), STOP and ASK the user:
+     "This project supports [list languages]. Should I create the content only in [user's language], or in every language?"
+   - If the user picks "every language", ASK whether to:
+     (a) reuse the same values across all languages, or
+     (b) translate the values into each language.
+     Build one entry per language in the "content" array accordingly.
+4. Only then call this tool.
+
+Use the returned contentTypes to build a valid payload. Follow these rules strictly:
+
+Field type rules (based on the "type" property of each field):
+- short-text: string value. If isArray is true, an array of strings.
+- long-text: markdown string. CRITICAL: If the markdown contains image references with local file paths (e.g. ![alt](./path/to/image.png)) or external URLs, you MUST first upload EACH image by calling upload-content-island-media for every image, then replace the original path/URL with the "url" returned by the upload. Only then call this tool with the updated markdown. Never leave local file paths in the markdown — they will not work. Code blocks must specify the language (e.g. \`\`\`typescript, \`\`\`bash, \`\`\`python, etc.). Cannot be an array.
+- number: numeric value. If isArray is true, an array of numbers.
+- boolean: true or false. Cannot be an array.
+- date: string in "yyyy-mm-dd" format. Cannot be an array.
+- date-time: ISO 8601 string (e.g. "2026-04-14T10:30:00Z"). Cannot be an array.
+- color: hexadecimal color string (e.g. "#FF5733"). Cannot be an array.
+- media: object with { name: string, url: string }. Upload first via upload-content-island-media. If isArray is true, an array of media objects.
+
+Fields whose "type" contains "|" (e.g. "abc123|Foo") are either ENUMS or RELATIONS — both look identical in "type", so you MUST disambiguate using "tsType":
+- ENUM (type contains "|" AND tsType starts with a single quote, e.g. "'M' | 'L' | 'XL'"): send a plain string equal to one of the values inside the union (e.g. "M"). If isArray is true, an array of those strings. NEVER send a content id or an object — only the plain string.
+- RELATION (type contains "|" AND tsType is exactly "string"): send the 24-char hex content id of an existing content of the related content type. If isArray is true, an array of ids. NEVER send a name or the value of a field — only the id.
+
+General rules:
+- Fields with isRequired: true MUST be included.
+- Provide one entry per language in the project's languages array.
+- contentType must match an existing content type name exactly.
+- Field names must match exactly as defined in the schema.
+
+Importing content from a web URL (blog posts, news articles, etc.):
+If the user asks you to create content from a web URL, follow this workflow:
+1. Fetch the URL and extract the relevant fields (title, body, author, etc.).
+2. Identify every image referenced in the extracted content (both in long-text markdown and in media fields).
+3. For EACH image, call upload-content-island-media with the image's absolute URL (e.g. "https://original-site.com/image.png"). This uploads the image to Content Island storage and returns a { name, url } object.
+4. Replace every original image URL in the extracted content with the "url" returned by upload-content-island-media. Never leave the original external URLs — they may become broken links if the source site removes them.
+5. Only then call this tool with the fully processed payload.`,
+    {
+      contentType: i.string().describe(
+        'The content type name (e.g. "post", "page"). Must match an existing content type name exactly. Use get-content-island-project to discover available content types.'
+      ),
+      name: i.string().describe("Display name for the new content entry."),
+      content: i.array(
+        i.object({
+          language: i.string().optional().describe(
+            `Language code (e.g. "en", "es"). Must be one of the languages from the project. Defaults to the project's first language if omitted.`
+          ),
+          fields: i.array(
+            i.object({
+              name: i.string().describe(
+                "Field name exactly as defined in the content type schema from get-content-island-project."
+              ),
+              value: i.any().describe(
+                "Field value. Must match the type and constraints of the field as described in the tool description above."
+              )
+            })
+          ).describe("Array of field name/value pairs. All fields with isRequired: true must be included.")
+        })
+      ).optional().describe(
+        "Content entries per language. Provide one entry per language in the project. If omitted, creates an empty content with no field values."
+      )
+    },
+    async ({ contentType: e, name: t, content: a }) => {
+      try {
+        const n = g(), o = { contentType: e, name: t, content: a }, s = await n.createContent(o);
+        return {
+          content: [{ type: "text", text: JSON.stringify(s, null, 2) }]
+        };
+      } catch (n) {
+        return h(n);
+      }
+    }
+  );
+}, D = () => {
+  u.tool(
+    "get-content-island-project",
+    `Get the user's Content Island project schema (languages and contentTypes).
+
+The contentTypes array mixes BOTH entities (item type: "entity", has a "fields" array) and enums (item type: "enum", has a "values" array).
+
+CRITICAL — Disambiguating fields whose "type" contains "|" (e.g. "abc123|Foo"):
+A field type that contains "|" can be either an ENUM or a RELATION to another entity. They look identical in "type". Use the field's "tsType" to tell them apart:
+  - tsType starts with a single quote (e.g. "'M' | 'L' | 'XL'") → the field is an ENUM. Valid values are the literal strings inside the union.
+  - tsType is exactly "string" → the field is a RELATION to a content of another type. Valid values are 24-char hex content ids.
+
+Always read tsType first when the type contains "|". Do NOT guess from the name.
+
+Each entity field also carries a "validations" array (optional). Each entry is { name, customArgs? } and may be one of: "required", "unique", "min-length", "max-length", "media-type". When you intend to write a value (via create-content-island-content or update-content-island-field-value), always check these validations and refuse to call the write tool if the user's value would fail any of them.
+
+The "languages" array at the project root lists every language the project supports. Field values are stored per language, so a single content entry may have one fieldValue per language. When writing, consider language coverage explicitly (see the write tools' descriptions).`,
+    async () => {
+      const t = await g().getProject();
+      return {
+        content: [{ type: "text", text: JSON.stringify(t, null, 2) }]
+      };
+    }
+  );
+}, m = 25, y = 100, _ = () => {
+  u.tool(
+    "list-content-island-contents",
+    `List content entries of the Content Island project. Returns the raw content structure with all fieldValues (each one carries its fieldName, language and value), so you can inspect every translation in one call. Drafts and unpublished values are included.
+
+IMPORTANT: Before calling this tool, you SHOULD call get-content-island-project to discover the available contentTypes and languages so the filters you pass are valid.
+
+Pagination:
+- The response always includes { items, skip, take, hasMore }.
+- Default take is ${m}, maximum allowed is ${y}.
+- If hasMore is true, call this tool again with skip = previous skip + previous take to fetch the next page. Repeat until hasMore is false (or items is empty).
+- hasMore is computed as items.length === take, so it can occasionally be a false positive when the total happens to be an exact multiple of take; in that case the next call returns an empty items array, which confirms the end of the list.
+
+Filters (all optional):
+- contentType: filter by content type name (e.g. "post"). Must match an existing content type from get-content-island-project.
+- id: a single content id, or an array of ids to fetch a specific subset.
+- language: restricts which fieldValues are included inside each content. NOTE: this does NOT remove contents from the result; a content without a translation in the given language will still appear, but with an empty fields array. If you need to discard those contents, filter them on your side.
+- status: filter by publication state. One of "draft" (never published), "changed" (published but has unpublished edits), "published" (in sync with the live state), or an array combining several. To find contents with unpublished data, pass status: ["draft", "changed"].
+- includeRelatedContent: when true, related content references are expanded inline in fieldValues.
+
+Each returned item includes a "status" field with the same values described above. Use it to tell apart fully-published contents from contents with pending changes.
+
+Sort (optional): object with any of:
+- contentType: "asc" | "desc"
+- lastUpdate: "asc" | "desc"`,
+    {
+      contentType: i.string().optional().describe("Filter by content type name. Must match an existing content type from get-content-island-project."),
+      id: i.union([i.string(), i.array(i.string())]).optional().describe("A single content id, or an array of ids to fetch a specific subset of contents."),
+      language: i.string().optional().describe(
+        'Language code (e.g. "en", "es"). Restricts which fieldValues are included inside each content. Does not remove contents that lack a translation in the given language.'
+      ),
+      status: i.union([i.enum(["draft", "changed", "published"]), i.array(i.enum(["draft", "changed", "published"]))]).optional().describe(
+        'Filter by publication state. Pass a single value (e.g. "draft") or an array (e.g. ["draft", "changed"]) to find contents with unpublished data.'
+      ),
+      includeRelatedContent: i.boolean().optional().describe("When true, related content references are expanded inline in fieldValues."),
+      sort: i.object({
+        contentType: i.enum(["asc", "desc"]).optional(),
+        lastUpdate: i.enum(["asc", "desc"]).optional()
+      }).optional().describe('Sort order. Each field is independently set to "asc" or "desc".'),
+      take: i.number().int().min(1).max(y).optional().describe(`Maximum number of items to return. Default ${m}, maximum ${y}.`),
+      skip: i.number().int().min(0).optional().describe("Number of items to skip from the start of the result set. Use for pagination.")
+    },
+    async ({ contentType: e, id: t, language: a, status: n, includeRelatedContent: o, sort: s, take: r, skip: d }) => {
+      try {
+        const l = g(), c = r ?? m, E = d ?? 0, p = {
+          pagination: { take: c, skip: E }
+        };
+        e !== void 0 && (p.contentType = e), t !== void 0 && (p.id = Array.isArray(t) ? { in: t } : t), a !== void 0 && (p.language = a), n !== void 0 && (p.status = Array.isArray(n) ? { in: n } : n), o !== void 0 && (p.includeRelatedContent = o), s !== void 0 && (p.sort = s);
+        const T = await l.getRawContentList(p), C = {
+          items: T,
+          skip: E,
+          take: c,
+          hasMore: T.length === c
+        };
+        return {
+          content: [{ type: "text", text: JSON.stringify(C, null, 2) }]
+        };
+      } catch (l) {
+        return h(l);
+      }
+    }
+  );
+}, $ = (e) => e?.type === "entity", b = (e) => !!(e == null || typeof e == "string" && e === "" || Array.isArray(e) && e.length === 0), N = (e, t) => t && Array.isArray(e) || typeof e == "string" ? e.length : null, V = (e) => {
+  const t = e.lastIndexOf(".");
+  return t === -1 ? null : e.slice(t);
+}, q = (e, t) => {
+  const a = typeof e == "string" ? e : e?.url;
+  if (typeof a != "string")
+    return !1;
+  const n = V(a);
+  return n !== null && t.includes(n);
+}, K = (e, t, a) => {
+  switch (e.name) {
+    case "required":
+    case "unique":
+      return null;
+    case "min-length": {
+      const n = N(t, a.isArray), o = e.customArgs?.length;
+      return n === null || typeof o != "number" ? null : n < o ? `expected min length ${o}, got ${n}` : null;
+    }
+    case "max-length": {
+      const n = N(t, a.isArray), o = e.customArgs?.length;
+      return n === null || typeof o != "number" ? null : n > o ? `expected max length ${o}, got ${n}` : null;
+    }
+    case "media-type": {
+      const n = (e.customArgs?.allowedExtensions ?? []).map((r) => r.name);
+      return n.length === 0 ? null : (a.isArray && Array.isArray(t) ? t : [t]).some((r) => !q(r, n)) ? `media file extension not in allowed list (${n.join(", ")})` : null;
+    }
+    default:
+      return null;
+  }
+}, W = (e, t) => {
+  const a = (e.contentTypes ?? []).find((r) => $(r) && r.name === t.contentType.name);
+  if (!a)
     return {
-      content: [{ type: "text", text: JSON.stringify(e, null, 2) }]
+      ok: !1,
+      errors: [`content type "${t.contentType.name}" not found in project schema`]
     };
-  });
-}, I = () => {
-  f();
+  const n = [], o = e.languages ?? [], s = t.fields ?? [];
+  for (const r of a.fields)
+    if (r.isRequired)
+      for (const d of o) {
+        const l = s.find((c) => c.name === r.name && c.language === d);
+        (!l || b(l.value)) && n.push(`required field "${r.name}" is empty in language "${d}"`);
+      }
+  for (const r of s) {
+    const d = a.fields.find((l) => l.name === r.name);
+    if (!(!d || b(r.value)))
+      for (const l of d.validations ?? []) {
+        const c = K(l, r.value, d);
+        c && n.push(`field "${r.name}" [${r.language}]: ${c}`);
+      }
+  }
+  return n.length === 0 ? { ok: !0 } : { ok: !1, errors: n };
+}, B = (e) => `Cannot publish content — preflight validation failed:
+${e.map((t) => `  - ${t}`).join(`
+`)}
+
+Fix the issues (e.g. via update-content-island-field-value) and retry. Use list-content-island-contents with the content id to inspect the current draft state.`, Y = () => {
+  u.tool(
+    "publish-content-island-content",
+    `Publish an existing content in the Content Island project. This promotes the current draft state to the live state visible to consumers without the PREVIEW_ token prefix. Requires a write token.
+
+What this tool does:
+- Runs a preflight that REFUSES to publish if the content is not valid (see "Preflight" below).
+- Snapshots the content's current draft fieldValues into publishedValues.
+- Sets the content's status to "published".
+- Idempotent: publishing a content that is already published refreshes the published snapshot from the current draft (useful after editing a previously published content).
+
+Preflight (server-side, ENFORCED — you cannot bypass it):
+The tool fetches the project schema and the current draft of the content, and rejects the call with an error listing every issue if any of the following fails:
+- Required fields: every field with isRequired: true must have a non-empty value in every project language. If a translation is missing, publish is blocked.
+- Field validations: every populated value must satisfy its "min-length", "max-length", and "media-type" validations. "unique" is enforced by the backend (not preflighted here).
+
+If the preflight rejects, the response lists all problems in one pass. Fix them (e.g. with update-content-island-field-value) and retry.
+
+WORKFLOW (recommended BEFORE calling this tool, to give the user feedback before the preflight runs):
+1. Call get-content-island-project to read the project schema (required fields, validations, languages).
+2. Call list-content-island-contents with id = contentId to inspect the current draft values.
+3. If you can already see that something is incomplete, ASK the user before attempting to publish — preflight will reject anyway but the user gets context sooner.
+4. Otherwise call this tool; preflight will confirm the content is valid and publish it.
+
+Errors:
+- 400 (preflight) if required fields are empty or validations fail. The message lists every issue.
+- 404 if the contentId does not exist.
+- 401/403 if the configured token is not a write token.`,
+    {
+      contentId: i.string().describe("The id of the existing content entry to publish.")
+    },
+    async ({ contentId: e }) => {
+      try {
+        const t = g(), [a, n] = await Promise.all([t.getProject(), t.getRawContent({ id: e })]);
+        if (!n)
+          return {
+            content: [{ type: "text", text: `Content "${e}" not found.` }],
+            isError: !0
+          };
+        const o = W(a, n);
+        return o.ok === !1 ? {
+          content: [{ type: "text", text: B(o.errors) }],
+          isError: !0
+        } : (await t.publishContent(e), {
+          content: [{ type: "text", text: JSON.stringify({ contentId: e, status: "published" }, null, 2) }]
+        });
+      } catch (t) {
+        return h(t);
+      }
+    }
+  );
+}, G = () => {
+  u.tool(
+    "update-content-island-field-value",
+    `Update or add a single field value of an existing content in the Content Island project. Requires a write token.
+
+Use this tool to:
+- Change the value of a field for an existing language (e.g. fix a typo in the English title).
+- Add a translation: insert the value of a field in a language that does not yet exist on the content.
+
+WORKFLOW (perform BEFORE calling this tool):
+1. Call get-content-island-project to fetch the project schema. Locate the field by name (case-sensitive) and read its "type", "isArray", "validations" array (each entry is { name, customArgs? }), and the project's "languages" list.
+2. Validate the user's intended value against the field's "validations":
+   - "required": value must be non-empty / non-null.
+   - "min-length" / "max-length": value.length (or array length when isArray) must satisfy customArgs.
+   - "unique": warn the user that the API will reject the call if another content of this type already has that value.
+   - "media-type": only file extensions listed in customArgs are allowed.
+   If any constraint would fail, do NOT call this tool — ask the user for a valid value first.
+3. Language coverage:
+   - If project.languages has more than one language and the user specified only one (or none), STOP and ASK the user:
+     "This project supports [list languages]. Should I update only the [user's language] value, or apply the change to every language?"
+   - If the user picks "every language", ASK whether to:
+     (a) reuse the same value in every language, or
+     (b) translate the value into each language.
+     For (b), produce a translation per language before calling.
+   - Call this tool once per language, each call with its corresponding value.
+4. Only then call this tool.
+
+Field type rules (must match the field "type"):
+- short-text: string. If isArray is true, an array of strings.
+- long-text: markdown string. CRITICAL: If the markdown contains image references with local file paths or external URLs, you MUST first upload EACH image via upload-content-island-media and replace the original path/URL with the "url" returned by the upload. Never leave local file paths in the markdown — they will not work. Code blocks must specify the language. Cannot be an array.
+- number: numeric value. If isArray is true, an array of numbers.
+- boolean: true or false. Cannot be an array.
+- date: string in "yyyy-mm-dd" format. Cannot be an array.
+- date-time: ISO 8601 string. Cannot be an array.
+- color: hexadecimal color string (e.g. "#FF5733"). Cannot be an array.
+- media: object with { name: string, url: string }. Upload first via upload-content-island-media. If isArray is true, an array of media objects.
+
+Fields whose "type" contains "|" (e.g. "abc123|Foo") are either ENUMS or RELATIONS — both look identical in "type", so you MUST disambiguate using "tsType":
+- ENUM (type contains "|" AND tsType starts with a single quote, e.g. "'M' | 'L' | 'XL'"): send a plain string equal to one of the values inside the union (e.g. "M"). If isArray is true, an array of those strings. NEVER send a content id or an object.
+- RELATION (type contains "|" AND tsType is exactly "string"): send the 24-char hex content id of an existing content of the related content type. If isArray is true, an array of ids. NEVER send a name.
+
+The tool always identifies the field by its name within the content type. If the field is renamed in the schema between calls, this tool will return a 404; refresh the schema with get-content-island-project and retry.`,
+    {
+      contentId: i.string().describe("The id of the existing content entry to update."),
+      fieldName: i.string().describe("Name of the field as defined in the content type schema (from get-content-island-project)."),
+      language: i.string().describe('Language code of the field value (e.g. "en", "es"). Must be one of the project languages.'),
+      value: i.any().describe(
+        "The new field value. Must match the type and isArray of the field as described in the tool description above."
+      )
+    },
+    async ({ contentId: e, fieldName: t, language: a, value: n }) => {
+      try {
+        return await g().updateContentFieldValue(e, { fieldName: t, language: a }, n), {
+          content: [
+            { type: "text", text: JSON.stringify({ contentId: e, fieldName: t, language: a, status: "updated" }, null, 2) }
+          ]
+        };
+      } catch (o) {
+        return h(o);
+      }
+    }
+  );
+}, H = {
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".gif": "image/gif",
+  ".webp": "image/webp",
+  ".avif": "image/avif",
+  ".svg": "image/svg+xml",
+  ".pdf": "application/pdf",
+  ".mp4": "video/mp4",
+  ".webm": "video/webm",
+  ".mov": "video/quicktime",
+  ".mp3": "audio/mpeg",
+  ".wav": "audio/wav"
+}, J = (e) => /^https?:\/\//i.test(e), X = async (e) => {
+  const t = await fetch(e);
+  if (!t.ok)
+    throw new Error(`Failed to fetch ${e}: ${t.status} ${t.statusText}`);
+  const a = await t.blob(), n = new URL(e).pathname, o = A(n) || "download";
+  return { blob: a, fileName: o };
+}, z = async (e) => {
+  const t = await S(e), a = R(e).toLowerCase(), n = H[a] ?? "application/octet-stream", o = new Blob([t], { type: n }), s = A(e);
+  return { blob: o, fileName: s };
+}, Q = () => {
+  u.tool(
+    "upload-content-island-media",
+    "Upload a media file to the Content Island project. Accepts a local file path or a URL (http/https). Requires a write token. Note: file attachments in the chat cannot be uploaded directly — provide the file path on disk or a public URL instead.",
+    {
+      source: i.string().describe(
+        'Path to a local file or a URL (http/https) pointing to the media to upload. Examples: "./assets/hero.png", "https://example.com/photo.jpg". File attachments in the conversation cannot be used directly — ask the user for the file path or URL.'
+      ),
+      fileName: i.string().optional().describe(
+        "Override the file name used in Content Island. Defaults to the file name from the source path or URL."
+      )
+    },
+    async ({ source: e, fileName: t }) => {
+      try {
+        const { blob: a, fileName: n } = J(e) ? await X(e) : await z(e), s = await g().uploadMedia({ file: a, fileName: t ?? n });
+        return {
+          content: [{ type: "text", text: JSON.stringify(s, null, 2) }]
+        };
+      } catch (a) {
+        return h(a);
+      }
+    }
+  );
+}, Z = () => {
+  D(), _(), F(), G(), Y(), Q();
 };
-E();
-I();
-const N = new d();
-await s.connect(N);
+P();
+Z();
+const ee = new O();
+await u.connect(ee);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@content-island/mcp",
-  "version": "0.1.13",
+  "version": "0.2.1",
   "description": "Content Island - MCP (Model Context Protocol) server",
   "private": false,
   "sideEffects": false,
@@ -33,7 +33,7 @@
     "type-check": "tsc --noEmit --preserveWatchOutput"
   },
   "dependencies": {
-    "@content-island/api-client": "0.18.0",
+    "@content-island/api-client": "0.20.0",
     "@modelcontextprotocol/sdk": "1.13.3",
     "zod": "3.25.71"
   },