@skemacms/mcp-server 1.1.0

package/README.md

@@ -0,0 +1,206 @@
+# Skema MCP Server
+
+[![npm version](https://img.shields.io/npm/v/@skemacms/mcp-server.svg)](https://www.npmjs.com/package/@skemacms/mcp-server)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+Serveur MCP (Model Context Protocol) officiel pour **Skema CMS**.  
+Connectez Claude Desktop, Cursor, Windsurf ou tout client MCP compatible à vos données Skema.
+
+## Installation
+
+```bash
+npm install -g @skemacms/mcp-server
+```
+
+## Configuration
+
+### Claude Desktop
+
+Ajoutez dans votre fichier `claude_desktop_config.json` :
+
+```json
+{
+  "mcpServers": {
+    "skema-cms": {
+      "command": "skema-mcp",
+      "env": {
+        "SKEMA_API_KEY": "pk_live_votre_cle_api",
+      }
+    }
+  }
+}
+```
+
+### Windsurf / Cursor
+
+Ajoutez dans vos paramètres MCP :
+
+```json
+{
+  "skema-cms": {
+    "command": "npx",
+    "args": ["-y", "@skemacms/mcp-server"],
+    "env": {
+      "SKEMA_API_KEY": "pk_live_votre_cle_api",
+    }
+  }
+}
+```
+
+## Variables d'environnement
+
+| Variable         | Description                                             | Requis |
+| ---------------- | ------------------------------------------------------- | ------ |
+| `SKEMA_API_KEY`  | Clé API Skema (format `pk_live_xxx`)                    | Oui    |
+| `SKEMA_BASE_URL` | URL de l'API Skema (défaut: `https://api.skemacms.com`) | Non    |
+
+## Outils disponibles (11 outils)
+
+### Lecture
+
+| Outil                     | Description                                                    |
+| ------------------------- | -------------------------------------------------------------- |
+| `get_collections`         | Liste toutes les collections accessibles                       |
+| `get_collection`          | Récupère le schéma d'une collection (champs, types, relations) |
+| `get_collection_items`    | Liste les items avec pagination, tri, filtres et populate      |
+| `get_collection_item`     | Récupère un item par son ID avec ses relations                 |
+| `search_collection_items` | Recherche textuelle dans une collection                        |
+| `count_collection_items`  | Compte les items avec filtres optionnels                       |
+
+### Écriture
+
+| Outil                    | Description                                     |
+| ------------------------ | ----------------------------------------------- |
+| `create_collection_item` | Crée un nouvel item                             |
+| `update_collection_item` | Met à jour un item existant (merge partiel)     |
+| `delete_collection_item` | Supprime un item                                |
+| `batch_create_items`     | Crée plusieurs items en une seule requête       |
+| `batch_update_items`     | Met à jour plusieurs items en une seule requête |
+
+## Exemples d'utilisation
+
+### Lister les collections
+
+```
+Quelles collections sont disponibles dans mon CMS ?
+```
+
+### Récupérer des items avec relations
+
+```
+Liste les 10 derniers articles avec leurs auteurs et catégories
+```
+
+### Créer un item
+
+```
+Crée un nouvel article avec le titre "Mon article" et le statut "draft"
+```
+
+### Recherche
+
+```
+Recherche les produits contenant "smartphone" dans le titre
+```
+
+### Opérations en masse
+
+```
+Mets à jour le statut de tous les articles de la catégorie "news" en "published"
+```
+
+## API HTTP (alternative)
+
+Vous pouvez aussi utiliser l'API MCP directement via HTTP :
+
+**Endpoint :** `POST https://api.skemacms.com/mcp`
+
+**Headers :**
+
+- `Authorization: Bearer <API_KEY>`
+- `Content-Type: application/json`
+
+### Exemple cURL
+
+```bash
+curl -X POST https://api.skemacms.com/mcp \
+  -H "Authorization: Bearer pk_live_xxx" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "jsonrpc": "2.0",
+    "id": 1,
+    "method": "tools/call",
+    "params": {
+      "name": "get_collection_items",
+      "arguments": {
+        "collection": "articles",
+        "page": 1,
+        "perPage": 10,
+        "populate": "author,category"
+      }
+    }
+  }'
+```
+
+### Exemple Python
+
+```python
+import requests
+
+API_KEY = "pk_live_xxx"
+MCP_URL = "https://api.skemacms.com/mcp"
+
+headers = {
+    "Authorization": f"Bearer {API_KEY}",
+    "Content-Type": "application/json"
+}
+
+response = requests.post(MCP_URL, headers=headers, json={
+    "jsonrpc": "2.0",
+    "id": 1,
+    "method": "tools/call",
+    "params": {
+        "name": "get_collection_items",
+        "arguments": {"collection": "articles", "populate": "author"}
+    }
+})
+print(response.json())
+```
+
+## Méthodes JSON-RPC
+
+| Méthode      | Description                         |
+| ------------ | ----------------------------------- |
+| `initialize` | Initialise la connexion MCP         |
+| `tools/list` | Liste tous les outils disponibles   |
+| `tools/call` | Exécute un outil avec ses arguments |
+
+## Permissions
+
+Les outils disponibles dépendent des permissions de votre clé API :
+
+| Permission | Outils autorisés               |
+| ---------- | ------------------------------ |
+| `read`     | `get_*`, `search_*`, `count_*` |
+| `create`   | `create_*`, `batch_create_*`   |
+| `update`   | `update_*`, `batch_update_*`   |
+| `delete`   | `delete_*`                     |
+
+## Développement local
+
+```bash
+git clone https://github.com/skemacms/mcp-server.git
+cd mcp-server
+npm install
+npm run dev
+```
+
+## Liens utiles
+
+- [Documentation Skema CMS](https://docs.skemacms.com)
+- [Guide MCP](https://docs.skemacms.com/guide/mcp)
+- [Créer une clé API](https://app.skemacms.com)
+
+## Licence
+
+MIT - Skema CMS

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+/**
+ * Serveur MCP pour Skema CMS
+ * Expose les fonctionnalités de gestion de contenu via le protocole MCP
+ */
+export {};

package/dist/index.js

@@ -0,0 +1,130 @@
+#!/usr/bin/env node
+/**
+ * Serveur MCP pour Skema CMS
+ * Expose les fonctionnalités de gestion de contenu via le protocole MCP
+ */
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { tools } from "./tools.js";
+import * as skema from "./skema-client.js";
+const server = new Server({
+    name: "skema-cms",
+    version: "1.0.0",
+}, {
+    capabilities: {
+        tools: {},
+    },
+});
+// Liste des outils disponibles
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools,
+}));
+// Execution des outils
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    try {
+        let result;
+        switch (name) {
+            // Collections
+            case "get_collections": {
+                result = await skema.getCollections();
+                break;
+            }
+            case "get_collection": {
+                const { collection } = args;
+                result = await skema.getCollection(collection);
+                break;
+            }
+            // Content CRUD
+            case "get_collection_items": {
+                const { collection, page, perPage, sort, populate, filters } = args;
+                result = await skema.getItems(collection, {
+                    page,
+                    perPage,
+                    sort,
+                    populate,
+                    filters,
+                });
+                break;
+            }
+            case "get_collection_item": {
+                const { collection, id, populate } = args;
+                result = await skema.getItem(collection, id, { populate });
+                break;
+            }
+            case "create_collection_item": {
+                const { collection, data } = args;
+                result = await skema.createItem(collection, data);
+                break;
+            }
+            case "update_collection_item": {
+                const { collection, id, data } = args;
+                result = await skema.updateItem(collection, id, data);
+                break;
+            }
+            case "delete_collection_item": {
+                const { collection, id } = args;
+                result = await skema.deleteItem(collection, id);
+                break;
+            }
+            case "search_collection_items": {
+                const { collection, query, fields, page, perPage } = args;
+                result = await skema.searchItems(collection, query, {
+                    fields,
+                    page,
+                    perPage,
+                });
+                break;
+            }
+            case "count_collection_items": {
+                const { collection, filters } = args;
+                result = await skema.countItems(collection, filters);
+                break;
+            }
+            case "batch_create_items": {
+                const { collection, items } = args;
+                result = await skema.batchCreate(collection, items);
+                break;
+            }
+            case "batch_update_items": {
+                const { collection, items } = args;
+                result = await skema.batchUpdate(collection, items);
+                break;
+            }
+            default:
+                throw new Error(`Outil inconnu: ${name}`);
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(result, null, 2),
+                },
+            ],
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(`Erreur outil ${name}:`, message);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Erreur: ${message}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+});
+// Démarrage du serveur
+const main = async () => {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("Serveur MCP Skema démarre");
+};
+main().catch((error) => {
+    console.error("Erreur fatale:", error);
+    process.exit(1);
+});

package/dist/skema-client.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Client HTTP pour communiquer avec l'API publique Skema
+ */
+export interface SkemaResponse<T = unknown> {
+    data: T;
+    count?: number;
+    page?: number;
+    totalPages?: number;
+    message: string;
+    statusCode: number;
+}
+export interface FetchOptions {
+    method?: "GET" | "POST" | "PUT" | "DELETE";
+    body?: unknown;
+    params?: Record<string, string | number | boolean | undefined>;
+}
+/**
+ * Effectue une requete vers l'API Skema
+ */
+export declare const skemaFetch: <T = unknown>(path: string, options?: FetchOptions) => Promise<SkemaResponse<T>>;
+/**
+ * Recupere la liste des collections
+ */
+export declare const getCollections: () => Promise<SkemaResponse<unknown>>;
+/**
+ * Recupere le schema d'une collection
+ */
+export declare const getCollection: (name: string) => Promise<SkemaResponse<unknown>>;
+/**
+ * Liste les items d'une collection
+ */
+export declare const getItems: (collection: string, options?: {
+    page?: number;
+    perPage?: number;
+    sort?: string;
+    populate?: string;
+    filters?: Record<string, unknown>;
+}) => Promise<SkemaResponse<unknown>>;
+/**
+ * Recupere un item par son ID
+ */
+export declare const getItem: (collection: string, id: string, options?: {
+    populate?: string;
+}) => Promise<SkemaResponse<unknown>>;
+/**
+ * Cree un nouvel item
+ */
+export declare const createItem: (collection: string, data: Record<string, unknown>) => Promise<SkemaResponse<unknown>>;
+/**
+ * Met a jour un item
+ */
+export declare const updateItem: (collection: string, id: string, data: Record<string, unknown>) => Promise<SkemaResponse<unknown>>;
+/**
+ * Supprime un item
+ */
+export declare const deleteItem: (collection: string, id: string) => Promise<SkemaResponse<unknown>>;
+/**
+ * Recherche dans une collection
+ */
+export declare const searchItems: (collection: string, query: string, options?: {
+    fields?: string;
+    page?: number;
+    perPage?: number;
+}) => Promise<SkemaResponse<unknown>>;
+/**
+ * Compte les items d'une collection
+ */
+export declare const countItems: (collection: string, filters?: Record<string, unknown>) => Promise<SkemaResponse<unknown>>;
+/**
+ * Cree plusieurs items en une seule requete
+ */
+export declare const batchCreate: (collection: string, items: Record<string, unknown>[]) => Promise<SkemaResponse<unknown>>;
+/**
+ * Met a jour plusieurs items en une seule requete
+ */
+export declare const batchUpdate: (collection: string, items: Array<{
+    id: string;
+} & Record<string, unknown>>) => Promise<SkemaResponse<unknown>>;

package/dist/skema-client.js

@@ -0,0 +1,116 @@
+/**
+ * Client HTTP pour communiquer avec l'API publique Skema
+ */
+const API_KEY = process.env.SKEMA_API_KEY || "";
+const BASE_URL = process.env.SKEMA_BASE_URL || "https://api.skemacms.com";
+/**
+ * Effectue une requete vers l'API Skema
+ */
+export const skemaFetch = async (path, options = {}) => {
+    const { method = "GET", body, params } = options;
+    let url = `${BASE_URL}${path}`;
+    if (params) {
+        const searchParams = new URLSearchParams();
+        Object.entries(params).forEach(([key, value]) => {
+            if (value !== undefined) {
+                searchParams.append(key, String(value));
+            }
+        });
+        const queryString = searchParams.toString();
+        if (queryString) {
+            url += `?${queryString}`;
+        }
+    }
+    const response = await fetch(url, {
+        method,
+        headers: {
+            "X-API-Key": API_KEY,
+            "Content-Type": "application/json",
+        },
+        ...(body ? { body: JSON.stringify(body) } : {}),
+    });
+    if (!response.ok) {
+        const error = await response
+            .json()
+            .catch(() => ({ message: "Erreur inconnue" }));
+        throw new Error(error.message || `Erreur HTTP ${response.status}`);
+    }
+    return response.json();
+};
+/**
+ * Recupere la liste des collections
+ */
+export const getCollections = () => skemaFetch("/public/collections");
+/**
+ * Recupere le schema d'une collection
+ */
+export const getCollection = (name) => skemaFetch(`/public/collections/${name}`);
+/**
+ * Liste les items d'une collection
+ */
+export const getItems = (collection, options) => skemaFetch(`/public/${collection}`, {
+    params: {
+        page: options?.page,
+        perPage: options?.perPage,
+        sort: options?.sort,
+        populate: options?.populate,
+        ...(options?.filters && { filters: JSON.stringify(options.filters) }),
+    },
+});
+/**
+ * Recupere un item par son ID
+ */
+export const getItem = (collection, id, options) => skemaFetch(`/public/${collection}/${id}`, {
+    params: { populate: options?.populate },
+});
+/**
+ * Cree un nouvel item
+ */
+export const createItem = (collection, data) => skemaFetch(`/public/${collection}`, {
+    method: "POST",
+    body: data,
+});
+/**
+ * Met a jour un item
+ */
+export const updateItem = (collection, id, data) => skemaFetch(`/public/${collection}/${id}`, {
+    method: "PUT",
+    body: data,
+});
+/**
+ * Supprime un item
+ */
+export const deleteItem = (collection, id) => skemaFetch(`/public/${collection}/${id}`, {
+    method: "DELETE",
+});
+/**
+ * Recherche dans une collection
+ */
+export const searchItems = (collection, query, options) => skemaFetch(`/public/${collection}/search`, {
+    params: {
+        q: query,
+        fields: options?.fields,
+        page: options?.page,
+        perPage: options?.perPage,
+    },
+});
+/**
+ * Compte les items d'une collection
+ */
+export const countItems = (collection, filters) => skemaFetch(`/public/${collection}/count`, {
+    params: filters ? { filters: JSON.stringify(filters) } : undefined,
+});
+/**
+ * Cree plusieurs items en une seule requete
+ */
+export const batchCreate = (collection, items) => skemaFetch(`/public/${collection}/batch`, {
+    method: "POST",
+    body: items,
+});
+/**
+ * Met a jour plusieurs items en une seule requete
+ */
+export const batchUpdate = (collection, items) => skemaFetch(`/public/${collection}/batch`, {
+    method: "PUT",
+    body: items,
+});

package/dist/tools.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Définition des outils MCP pour Skema
+ * Version 2 : 11 outils (sans get_related_items, on utilise populate)
+ */
+import type { Tool } from "@modelcontextprotocol/sdk/types.js";
+export declare const tools: Tool[];

package/dist/tools.js

@@ -0,0 +1,235 @@
+/**
+ * Définition des outils MCP pour Skema
+ * Version 2 : 11 outils (sans get_related_items, on utilise populate)
+ */
+export const tools = [
+    {
+        name: "get_collections",
+        description: "Liste toutes les collections accessibles avec la clé API configurée",
+        inputSchema: {
+            type: "object",
+            properties: {},
+            required: [],
+        },
+    },
+    {
+        name: "get_collection",
+        description: "Récupère le schéma complet d'une collection (champs, types, relations)",
+        inputSchema: {
+            type: "object",
+            properties: {
+                collection: {
+                    type: "string",
+                    description: "Nom de la collection",
+                },
+            },
+            required: ["collection"],
+        },
+    },
+    {
+        name: "get_collection_items",
+        description: "Liste les items d'une collection avec pagination, tri, filtres et populate",
+        inputSchema: {
+            type: "object",
+            properties: {
+                collection: {
+                    type: "string",
+                    description: "Nom de la collection",
+                },
+                page: {
+                    type: "number",
+                    description: "Numéro de page (défaut: 1)",
+                },
+                perPage: {
+                    type: "number",
+                    description: "Items par page (défaut: 20, max: 100)",
+                },
+                sort: {
+                    type: "string",
+                    description: "Champ de tri. Préfixe - pour descendant (ex: -created_at)",
+                },
+                populate: {
+                    type: "string",
+                    description: "Relations à inclure, séparées par des virgules (ex: author,category)",
+                },
+                filters: {
+                    type: "object",
+                    description: "Filtres JSON (ex: { status: 'active' })",
+                },
+            },
+            required: ["collection"],
+        },
+    },
+    {
+        name: "get_collection_item",
+        description: "Récupère un item spécifique par son ID avec ses relations (populate)",
+        inputSchema: {
+            type: "object",
+            properties: {
+                collection: {
+                    type: "string",
+                    description: "Nom de la collection",
+                },
+                id: {
+                    type: "string",
+                    description: "ID de l'item (UUID)",
+                },
+                populate: {
+                    type: "string",
+                    description: "Relations à inclure, séparées par des virgules",
+                },
+            },
+            required: ["collection", "id"],
+        },
+    },
+    {
+        name: "create_collection_item",
+        description: "Crée un nouvel item dans une collection",
+        inputSchema: {
+            type: "object",
+            properties: {
+                collection: {
+                    type: "string",
+                    description: "Nom de la collection",
+                },
+                data: {
+                    type: "object",
+                    description: "Données de l'item à créer",
+                },
+            },
+            required: ["collection", "data"],
+        },
+    },
+    {
+        name: "update_collection_item",
+        description: "Met à jour un item existant (merge partiel)",
+        inputSchema: {
+            type: "object",
+            properties: {
+                collection: {
+                    type: "string",
+                    description: "Nom de la collection",
+                },
+                id: {
+                    type: "string",
+                    description: "ID de l'item à modifier",
+                },
+                data: {
+                    type: "object",
+                    description: "Données à mettre à jour",
+                },
+            },
+            required: ["collection", "id", "data"],
+        },
+    },
+    {
+        name: "delete_collection_item",
+        description: "Supprime un item d'une collection",
+        inputSchema: {
+            type: "object",
+            properties: {
+                collection: {
+                    type: "string",
+                    description: "Nom de la collection",
+                },
+                id: {
+                    type: "string",
+                    description: "ID de l'item à supprimer",
+                },
+            },
+            required: ["collection", "id"],
+        },
+    },
+    {
+        name: "search_collection_items",
+        description: "Recherche textuelle dans une collection",
+        inputSchema: {
+            type: "object",
+            properties: {
+                collection: {
+                    type: "string",
+                    description: "Nom de la collection",
+                },
+                query: {
+                    type: "string",
+                    description: "Terme de recherche",
+                },
+                fields: {
+                    type: "string",
+                    description: "Champs où chercher, séparés par des virgules (ex: title,description)",
+                },
+                page: {
+                    type: "number",
+                    description: "Numéro de page",
+                },
+                perPage: {
+                    type: "number",
+                    description: "Items par page",
+                },
+            },
+            required: ["collection", "query"],
+        },
+    },
+    {
+        name: "count_collection_items",
+        description: "Compte le nombre d'items dans une collection avec filtres optionnels",
+        inputSchema: {
+            type: "object",
+            properties: {
+                collection: {
+                    type: "string",
+                    description: "Nom de la collection",
+                },
+                filters: {
+                    type: "object",
+                    description: "Filtres JSON optionnels",
+                },
+            },
+            required: ["collection"],
+        },
+    },
+    {
+        name: "batch_create_items",
+        description: "Crée plusieurs items en une seule requête",
+        inputSchema: {
+            type: "object",
+            properties: {
+                collection: {
+                    type: "string",
+                    description: "Nom de la collection",
+                },
+                items: {
+                    type: "array",
+                    items: { type: "object" },
+                    description: "Tableau d'items à créer",
+                },
+            },
+            required: ["collection", "items"],
+        },
+    },
+    {
+        name: "batch_update_items",
+        description: "Met à jour plusieurs items en une seule requête",
+        inputSchema: {
+            type: "object",
+            properties: {
+                collection: {
+                    type: "string",
+                    description: "Nom de la collection",
+                },
+                items: {
+                    type: "array",
+                    items: {
+                        type: "object",
+                        properties: {
+                            id: { type: "string" },
+                        },
+                        required: ["id"],
+                    },
+                    description: "Tableau d'items avec leur ID et les données à modifier",
+                },
+            },
+            required: ["collection", "items"],
+        },
+    },
+];

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@skemacms/mcp-server",
+  "version": "1.1.0",
+  "description": "Serveur MCP officiel pour Skema CMS - Connectez Claude Desktop a vos donnees",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "skema-mcp": "./dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsx src/index.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": ["mcp", "skema", "cms", "headless", "claude", "ai", "model-context-protocol"],
+  "author": "Skema <contact@skemacms.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/skemacms/mcp-server.git"
+  },
+  "homepage": "https://docs.skemacms.com/guide/mcp",
+  "bugs": {
+    "url": "https://github.com/skemacms/mcp-server/issues"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.0.9",
+    "tsx": "^4.7.0",
+    "typescript": "^5.3.0"
+  }
+}