@content-island/mcp 0.1.0

package/README.md

@@ -0,0 +1,144 @@
+# @content-island/mcp
+
+## Content Island MCP
+
+A Model Context Protocol (MCP) server that enables seamless integration between modern web frameworks and [Content Island](https://contentisland.net/) headless CMS. This server empowers LLMs to scaffold, configure, and build web applications using frameworks like Astro, Next.js, Nuxt, and others while automatically integrating with Content Island's content management capabilities.
+
+### Key Features
+
+- **Modern framework support**. Scaffold projects with Astro, Next.js, Nuxt, SvelteKit, and other popular frameworks.
+- **Headless CMS integration**. Seamlessly connect to your Content Island project, retrieve content models, and configure data fetching.
+- **Content-driven development**. Generate components, pages, and data fetching logic based on your Content Island schema.
+- **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.
+
+### Requirements
+
+- Node.js 18 or newer
+- VS Code, Cursor, Windsurf, Claude Desktop or any other MCP client
+
+### Getting started
+
+First, install the Content Island MCP server with your client. A typical configuration looks like this:
+
+```js
+{
+  "mcpServers": {
+    "contentIsland": {
+      "command": "npx",
+      "args": [
+        "@content-island/mcp@latest"
+      ],
+      "env": {
+        "CONTENT_ISLAND_ACCESS_TOKEN": "<YOUR_CONTENT_ISLAND_ACCESS_TOKEN>"
+      }
+    }
+  }
+}
+```
+
+> **Note**: Replace `<YOUR_CONTENT_ISLAND_ACCESS_TOKEN>` with your actual Content Island project token. You can get it from the [Content Island account](https://docs.contentisland.net/ui/project/general/).
+
+[<img src="https://img.shields.io/badge/VS_Code-VS_Code?style=flat-square&label=Install%20Server&color=0098FF" alt="Install in VS Code">](https://insiders.vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522contentIsland%2522%252C%2522command%2522%253A%2522npx%2522%252C%2522args%2522%253A%255B%2522%2540content-island%252Fmcp%2540latest%2522%255D%252C%2522env%2522%253A%2520%257B%2522CONTENT_ISLAND_ACCESS_TOKEN%2522%253A%2522%253CYOUR_CONTENT_ISLAND_ACCESS_TOKEN%253E%2522%257D%257D) [<img alt="Install in VS Code Insiders" src="https://img.shields.io/badge/VS_Code_Insiders-VS_Code_Insiders?style=flat-square&label=Install%20Server&color=24bfa5">](https://insiders.vscode.dev/redirect?url=vscode-insiders%3Amcp%2Finstall%3F%257B%2522name%2522%253A%2522contentIsland%2522%252C%2522command%2522%253A%2522npx%2522%252C%2522args%2522%253A%255B%2522%2540content-island%252Fmcp%2540latest%2522%255D%252C%2522env%2522%253A%2520%257B%2522CONTENT_ISLAND_ACCESS_TOKEN%2522%253A%2522%253CYOUR_CONTENT_ISLAND_ACCESS_TOKEN%253E%2522%257D%257D)
+
+<details><summary><b>Install in VS Code</b></summary>
+
+You can also install the Content Island MCP server using the VS Code CLI:
+
+```bash
+# For VS Code
+code --add-mcp '{"name":"contentIsland","command":"npx","args":["@content-island/mcp@latest"],"env": {"CONTENT_ISLAND_ACCESS_TOKEN":"<YOUR_CONTENT_ISLAND_ACCESS_TOKEN>"}}'
+```
+
+> **Note**: Replace `<YOUR_CONTENT_ISLAND_ACCESS_TOKEN>` with your actual Content Island project token. You can get it from the [Content Island account](https://docs.contentisland.net/ui/project/general/).
+
+After installation, the Content Island MCP server will be available for use with your GitHub Copilot agent in VS Code.
+
+</details>
+
+<details>
+<summary><b>Install in Cursor</b></summary>
+
+#### Click the button to install:
+
+[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/install-mcp?name=contentIsland&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyJAY29udGVudC1pc2xhbmQvbWNwQGxhdGVzdCJdLCJlbnYiOnsiQ09OVEVOVF9JU0xBTkRfQUNDRVNTX1RPS0VOIjoiPFlPVVJfQ09OVEVOVF9JU0xBTkRfQUNDRVNTX1RPS0VOPiJ9fQ%3D%3D)
+
+#### Or install manually:
+
+Go to `Cursor Settings` -> `MCP` -> `Add new MCP Server`. Name to your liking, use `command` type with the command `npx @content-island/mcp@latest`. You can also verify config or add command like arguments via clicking `Edit`.
+
+```json
+{
+  "mcpServers": {
+    "contentIsland": {
+      "command": "npx",
+      "args": ["@content-island/mcp@latest"],
+      "env": {
+        "CONTENT_ISLAND_ACCESS_TOKEN": "<YOUR_CONTENT_ISLAND_ACCESS_TOKEN>"
+      }
+    }
+  }
+}
+```
+
+> **Note**: Replace `<YOUR_CONTENT_ISLAND_ACCESS_TOKEN>` with your actual Content Island project token. You can get it from the [Content Island account](https://docs.contentisland.net/ui/project/general/).
+
+</details>
+
+<details>
+<summary><b>Install in Windsurf</b></summary>
+
+Follow Windsurf MCP [documentation](https://docs.windsurf.com/windsurf/cascade/mcp). Use following configuration:
+
+```json
+{
+  "mcpServers": {
+    "contentIsland": {
+      "command": "npx",
+      "args": ["@content-island/mcp@latest"],
+      "env": {
+        "CONTENT_ISLAND_ACCESS_TOKEN": "<YOUR_CONTENT_ISLAND_ACCESS_TOKEN>"
+      }
+    }
+  }
+}
+```
+
+> **Note**: Replace `<YOUR_CONTENT_ISLAND_ACCESS_TOKEN>` with your actual Content Island project token. You can get it from the [Content Island account](https://docs.contentisland.net/ui/project/general/).
+
+</details>
+
+<details>
+<summary><b>Install in Claude Desktop</b></summary>
+
+Follow the MCP install [guide](https://modelcontextprotocol.io/quickstart/user), use following configuration:
+
+```json
+{
+  "mcpServers": {
+    "contentIsland": {
+      "command": "npx",
+      "args": ["@content-island/mcp@latest"],
+      "env": {
+        "CONTENT_ISLAND_ACCESS_TOKEN": "<YOUR_CONTENT_ISLAND_ACCESS_TOKEN>"
+      }
+    }
+  }
+}
+```
+
+> **Note**: Replace `<YOUR_CONTENT_ISLAND_ACCESS_TOKEN>` with your actual Content Island project token. You can get it from the [Content Island account](https://docs.contentisland.net/ui/project/general/).
+
+</details>
+
+### `Environment Variables`
+
+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`                                  |

package/cli.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+await import('./dist/index.js');

package/dist/index.js

@@ -0,0 +1,327 @@
+import { z as n } from "zod";
+import { McpServer as c } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { createClient as d } from "@content-island/api-client";
+import { StdioServerTransport as p } from "@modelcontextprotocol/sdk/server/stdio.js";
+const i = {
+  CONTENT_ISLAND_ACCESS_TOKEN: process.env.CONTENT_ISLAND_ACCESS_TOKEN,
+  CONTENT_ISLAND_DOMAIN: process.env.CONTENT_ISLAND_DOMAIN || void 0,
+  CONTENT_ISLAND_SECURE_PROTOCOL: process.env.CONTENT_ISLAND_SECURE_PROTOCOL !== "false",
+  CONTENT_ISLAND_API_VERSION: process.env.CONTENT_ISLAND_API_VERSION || void 0
+}, g = "0.1.0", u = {
+  version: g
+}, r = new c({
+  name: "Content Island",
+  version: u.version
+}), m = () => {
+  r.prompt(
+    "create-content-island-project",
+    "Professional MCP Server prompt for creating modern frontend projects integrated with Content Island CMS",
+    {
+      framework: n.string().describe("Framework choice (Next.js, Astro, Nuxt, etc.)"),
+      pages: n.string().describe("Pages needed (Homepage, Blog, Contact, etc.)"),
+      location: n.string().describe("Project location (root directory or subfolder name)"),
+      styling: n.string().describe("Styling preference (Tailwind CSS or custom)"),
+      design: n.string().describe("Design assets (mockups, wireframes, or none)")
+    },
+    async (l) => {
+      const { framework: e, pages: o, location: s, styling: t, design: a } = l;
+      return e && o && s && t && a ? {
+        description: "Content Island project generator",
+        messages: [
+          {
+            role: "assistant",
+            content: {
+              type: "text",
+              text: `# Content Island Website Generator
+
+I'll create a professional ${e} application integrated with your Content Island project.
+
+**Configuration:**
+- Framework: **${e}**
+- Pages: ${o}
+- Location: ${s}
+- Styling: ${t}
+- Design: ${a}
+
+# 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.
+
+## MANDATORY EXECUTION SEQUENCE - NO EXCEPTIONS
+
+### STEP 1: DATA RETRIEVAL (REQUIRED FIRST ACTION)
+- You MUST call the 'get-content-island-project' tool as your FIRST action
+- DO NOT proceed with ANY code generation until you have the project structure
+- Parse the returned JSON to extract: project languages, content types, and field definitions
+- If the tool fails, STOP and ask user to check their Content Island configuration
+
+### STEP 2: PACKAGE INSTALLATION (MANDATORY BEFORE CODE GENERATION)
+${e === "Nuxt" ? `
+- FIRST install the official Content Island packages:
+  * npm install @content-island/nuxt@latest
+  * npm install @content-island/api-client@latest
+- Add @content-island/nuxt to nuxt.config.ts modules array: modules: ['@content-island/nuxt']
+- Use Nuxt-specific Content Island composables from @content-island/nuxt
+- Use TypeScript types from @content-island/api-client
+` : `
+- FIRST install the official Content Island API client: npm install @content-island/api-client@latest
+- Add it to package.json dependencies
+`}
+- NEVER create custom API implementations
+- NEVER invent API methods that don't exist
+
+### STEP 3: TYPESCRIPT INTERFACE GENERATION (EXACT MAPPING REQUIRED)
+- Import Media type from '@content-island/api-client' if needed: import type { Media } from '@content-island/api-client'
+- Generate TypeScript interfaces using EXACTLY the structure returned by the tool
+- For EACH content type in the project data, create ONE interface
+- Interface naming: Use exact 'name' field from content type, capitalize first letter
+- MANDATORY fields for ALL interfaces:
+  * id: string
+  * language: union type of ALL languages from project.languages array
+- For each field in contentType.fields array:
+  * Use field.name exactly as property name
+  * Use field.tsType for TypeScript type
+  * If field.type === "media", use Media type from '@content-island/api-client'
+  * If field.isArray === true, make property an array: field.tsType[]
+  * If field.isRequired === false, make property optional with ?
+- For relationship fields (type contains "|"), use string[] for IDs storage
+- EXAMPLE transformation (follow this pattern exactly):
+  Field: {"name": "title", "type": "short-text", "tsType": "string", "isArray": false, "isRequired": true}
+  Result: title: string;
+
+### STEP 4: API CLIENT IMPLEMENTATION (DOCUMENTED METHODS ONLY)
+${e === "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
+` : `
+- Create client configuration file at: src/lib/content-island.ts (or equivalent based on framework)
+- Consult the official Content Island documentation to implement appropriate queries:
+  * Documentation: https://docs.contentisland.net/client-api/get-content/
+  * Documentation: https://docs.contentisland.net/client-api/get-content-list/
+- Available query parameters for both methods:
+  * id?: Filter (string or { in: string[] })
+  * contentType?: Filter (string or { in: string[] })
+  * language?: Filter (string or { in: string[] })
+  * 'fields.[fieldName]'?: Filter (for any field, e.g., 'fields.slug': 'my-post')
+- Analyze the project structure and requested pages to determine which queries are needed
+- Common patterns based on page types:
+  * List pages: client.getContentList<T>({ contentType: 'typename' })
+  * Detail pages: client.getContent<T>({ 'fields.slug': slug }) or client.getContent<T>({ id: 'content-id' })
+  * Multi-language: Add language filter to any query
+  * Related content: Use id: { in: string[] } for multiple items
+- Import client: import { createClient } from '@content-island/api-client';
+- Access token: import.meta.env.CONTENT_ISLAND_ACCESS_TOKEN
+`}
+- For EACH content type, analyze the requested pages and generate appropriate functions:
+  * List functions: getContentTypeList(language?: string) -> client.getContentList<ContentType>({ contentType: 'typename', ...(language && { language }) })
+  * Detail functions based on available fields:
+    - If has slug field: getContentTypeBySlug(slug: string, language?: string) -> client.getContent<ContentType>({ 'fields.slug': slug, ...(language && { language }) })
+    - By ID: getContentTypeById(id: string, language?: string) -> client.getContent<ContentType>({ id, ...(language && { language }) })
+  * Bulk functions if needed: getContentTypeByIds(ids: string[], language?: string) -> client.getContentList<ContentType>({ id: { in: ids }, ...(language && { language }) })
+  * Relationship functions: For fields that reference other content types
+- Implement only the functions actually needed for the requested pages
+- Always include language parameter support for multi-language projects
+
+
+### STEP 5: PROJECT STRUCTURE GENERATION (FRAMEWORK-SPECIFIC)
+- Framework: ${e}
+- Location: ${s}
+- Pages requested: ${o}
+- Styling: ${t}
+- Design approach: ${a}
+
+#### FRAMEWORK-SPECIFIC REQUIREMENTS:
+${e === "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" ? `
+- 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" ? `
+- Use Nuxt 3 composition API
+- Implement useFetch for data fetching
+- Create proper pages/ directory structure
+- Use NuxtImg for image optimization
+- Implement proper SEO with useHead
+` : ""}
+
+### STEP 6: ENVIRONMENT CONFIGURATION (MANDATORY FILES)
+${e === "Nuxt" ? `
+- Configure Content Island in nuxt.config.ts:
+  runtimeConfig: {
+    contentIsland: {
+      accessToken: process.env.CONTENT_ISLAND_ACCESS_TOKEN
+    }
+  }
+- Create .env file with: CONTENT_ISLAND_ACCESS_TOKEN=your_token_here
+` : `
+- Create .env file with: CONTENT_ISLAND_ACCESS_TOKEN=your_token_here
+`}
+- Add .env to .gitignore if not present
+- Document environment setup in README.md
+
+### STEP 7: STYLING IMPLEMENTATION
+${t.toLowerCase().includes("tailwind") ? `
+- Install and configure Tailwind CSS according to ${e} 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 ${t} according to ${e} best practices
+- Create modular CSS structure
+- Implement responsive design with media queries
+- Ensure accessibility with proper contrast and focus states
+`}
+
+### STEP 8: ERROR HANDLING & UX (NON-NEGOTIABLE REQUIREMENTS)
+- Implement loading states for ALL data fetching operations
+- Create error boundaries/components for content display failures
+- Add try-catch blocks around ALL API calls
+- Validate API responses before rendering (check for required fields)
+- Create fallback components for missing content
+- Show user-friendly error messages (no technical details to users)
+- Implement 404 pages for missing content
+
+### STEP 9: PERFORMANCE OPTIMIZATION (MANDATORY)
+- Implement lazy loading for images using framework-specific solutions
+- Use proper code splitting for JavaScript bundles
+- Optimize bundle sizes with tree shaking
+- Implement appropriate caching strategies for API responses
+- Use efficient data fetching patterns (avoid unnecessary re-renders)
+
+### STEP 10: ACCESSIBILITY & SEO (WCAG COMPLIANCE REQUIRED)
+- Use semantic HTML elements (header, nav, main, section, article, footer)
+- Implement proper heading hierarchy (h1, h2, h3...)
+- Add alt attributes to ALL images
+- Ensure keyboard navigation works for ALL interactive elements
+- Implement proper focus indicators
+- Add ARIA labels where necessary
+- Generate proper meta tags for SEO (title, description, og tags)
+- Implement structured data where appropriate
+
+### STEP 11: INTERNATIONALIZATION (IF APPLICABLE)
+- If project.languages contains multiple languages:
+  * Implement language detection based on URL or user preference
+  * Create language switching functionality
+  * Handle URL structure for multilingual content (/en/..., /es/...)
+  * Add fallbacks for unavailable translations
+  * Show appropriate messages when content not available in selected language
+
+### STEP 12: DOCUMENTATION GENERATION (COMPREHENSIVE REQUIRED)
+- Create README.md with:
+  * Project title and description
+  * Prerequisites (Node.js version, package manager)
+  * Installation instructions (step-by-step)
+  * Environment setup (copying .env, getting Content Island token)
+  * Development commands (dev server, build, preview)
+  * Project structure explanation (folders, key files)
+  * Content types description (based on project structure)
+  * API functions documentation (with examples)
+  * Deployment instructions
+  * Troubleshooting section
+
+## ABSOLUTE CONSTRAINTS - NEVER VIOLATE THESE:
+
+1. NEVER invent Content Island API methods not documented
+2. NEVER create example/dummy interfaces - use ONLY project structure data
+3. NEVER proceed without calling get-content-island-project tool first
+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"})
+5. NEVER skip error handling implementation
+6. NEVER ignore accessibility requirements
+7. NEVER use deprecated framework patterns
+8. NEVER hardcode content - fetch from Content Island API
+9. NEVER create TypeScript interfaces that don't match exact project structure
+10. NEVER skip any of the 12 implementation steps
+11. NEVER assume functionality exists without documentation
+12. NEVER create custom API clients when official one exists
+
+## VALIDATION CHECKLIST - VERIFY BEFORE COMPLETION:
+□ get-content-island-project tool called and data parsed
+${e === "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
+□ All content types have corresponding functions using Nuxt composables
+` : `
+□ @content-island/api-client@latest installed in package.json
+□ Media type imported from '@content-island/api-client' when needed
+□ All content types have corresponding API functions using official client
+`}
+□ TypeScript interfaces exactly match project structure
+□ All requested pages (${o}) are implemented
+□ Error handling implemented for all API calls
+□ Loading states implemented for all data fetching
+□ Responsive design implemented
+□ Accessibility features implemented
+□ SEO meta tags implemented
+□ Environment configuration documented
+□ README.md with complete setup instructions
+□ All framework-specific best practices followed
+
+FAILURE TO FOLLOW ANY OF THESE INSTRUCTIONS IS UNACCEPTABLE. DOUBLE-CHECK EVERY REQUIREMENT.
+
+Let me start by getting your Content Island project details...`
+            }
+          }
+        ]
+      } : {
+        description: "Please answer the required questions before proceeding.",
+        messages: [
+          {
+            role: "assistant",
+            content: {
+              type: "text",
+              text: `# Content Island Website Generator
+
+I need some information to create your Content Island website:
+
+**Required Information:**
+
+1. **Framework**: Which framework would you like to use? (Next.js, Astro, Nuxt, SvelteKit, etc.)
+
+2. **Pages**: What pages do you need? (e.g., "Homepage, Blog listing, Blog detail, About, Contact")
+
+3. **Location**: Where should I create the project? (e.g., "root directory" or "my-website" folder)
+
+4. **Styling**: How would you like to style the application? (e.g., "Tailwind CSS", "CSS Modules", "Styled Components")
+
+5. **Design**: Do you have design assets? (e.g., "I have wireframes", "Use best practices", "Minimal design")
+
+Please provide all this information so I can create your project.`
+            }
+          }
+        ]
+      };
+    }
+  );
+}, E = () => {
+  m();
+}, f = () => {
+  r.tool("get-content-island-project", "Get the user's Content Island project details", async () => {
+    const e = await d({
+      accessToken: i.CONTENT_ISLAND_ACCESS_TOKEN,
+      domain: i.CONTENT_ISLAND_DOMAIN,
+      secureProtocol: i.CONTENT_ISLAND_SECURE_PROTOCOL,
+      apiVersion: i.CONTENT_ISLAND_API_VERSION
+    }).getProject();
+    return {
+      content: [{ type: "text", text: JSON.stringify(e, null, 2) }]
+    };
+  });
+}, I = () => {
+  f();
+};
+E();
+I();
+const N = new p();
+await r.connect(N);

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@content-island/mcp",
+  "version": "0.1.0",
+  "description": "Content Island - MCP (Model Context Protocol) server",
+  "private": false,
+  "sideEffects": false,
+  "author": "Lemoncode",
+  "license": "MIT",
+  "files": [
+    "cli.js",
+    "dist"
+  ],
+  "bin": {
+    "mcp-server-content-island": "./cli.js"
+  },
+  "type": "module",
+  "module": "./dist/index.js",
+  "main": "./dist/index.umd.cjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.umd.cjs"
+    }
+  },
+  "imports": {
+    "#**": "./src/*"
+  },
+  "scripts": {
+    "build": "vite build",
+    "debug": "npm run build && npx @modelcontextprotocol/inspector node ./dist/index",
+    "type-check": "tsc --noEmit --preserveWatchOutput"
+  },
+  "dependencies": {
+    "@content-island/api-client": "^0.8.1",
+    "@modelcontextprotocol/sdk": "^1.13.3",
+    "zod": "^3.25.71"
+  },
+  "devDependencies": {
+    "@modelcontextprotocol/inspector": "^0.15.0"
+  }
+}