@firecms/mcp-server 3.3.0-canary.451aa49 → 3.3.0-canary.69e5ab1

package/src/tools/collection-schemas.ts

@@ -0,0 +1,316 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { FireCMSApiClient } from "../api-client.js";
+
+/**
+ * Property schema definition for collection properties.
+ * Supports all FireCMS property types.
+ */
+const PropertySchema = z.object({
+    dataType: z.enum([
+        "string", "number", "boolean", "date", "map",
+        "array", "geopoint", "reference",
+    ]).describe("The data type of this property"),
+    name: z.string().optional().describe("Display name for the property"),
+    description: z.string().optional().describe("Description shown as a tooltip"),
+    validation: z.record(z.any()).optional().describe("Validation rules (e.g., { required: true, min: 0, max: 100 })"),
+    enumValues: z.array(z.object({
+        id: z.string().describe("Enum value ID"),
+        label: z.string().describe("Display label"),
+        color: z.string().optional().describe("Color for the enum chip"),
+    })).optional().describe("Enum values for string/number fields (renders as select/chips)"),
+    multiline: z.boolean().optional().describe("For strings: render as textarea"),
+    markdown: z.boolean().optional().describe("For strings: render as markdown editor"),
+    url: z.union([z.boolean(), z.enum(["image", "video", "audio"])]).optional().describe("For strings: treat as URL, optionally specify media type"),
+    email: z.boolean().optional().describe("For strings: validate as email"),
+    storage: z.object({
+        storagePath: z.string().describe("Firebase Storage path"),
+        acceptedFiles: z.array(z.string()).optional().describe("Accepted MIME types"),
+        maxSize: z.number().optional().describe("Max file size in bytes"),
+    }).optional().describe("For strings: file upload configuration"),
+    of: z.any().optional().describe("For arrays: the property definition of array items"),
+    properties: z.record(z.any()).optional().describe("For maps: nested property definitions"),
+    path: z.string().optional().describe("For references: target collection path"),
+    previewProperties: z.array(z.string()).optional().describe("For references: properties to show in preview"),
+    disabled: z.boolean().optional().describe("If true, field is read-only in the form"),
+    columnWidth: z.number().optional().describe("Column width in pixels for table view"),
+    hideFromCollection: z.boolean().optional().describe("If true, hide from the table view"),
+}).passthrough();
+
+/**
+ * Register collection schema CRUD tools — manage the collection configurations
+ * stored in FireCMS Cloud. Admin-only operations.
+ */
+export function registerCollectionSchemaTools(server: McpServer, api: FireCMSApiClient) {
+
+    // ─── 1. List all collection schemas ────────────────────
+
+    server.registerTool(
+        "list_collection_schemas",
+        {
+            description: `List all persisted collection schemas for a FireCMS project. Returns the collection 
+configurations (name, path, properties, etc.) that define how data is displayed and edited in the CMS.`,
+            inputSchema: {
+                projectId: z.string().describe("Firebase project ID"),
+            },
+            annotations: { readOnlyHint: true },
+        },
+        async ({ projectId }) => {
+            try {
+                await api.assertAdmin(projectId);
+                const schemas = await api.listCollectionSchemas(projectId);
+                return {
+                    content: [{
+                        type: "text" as const,
+                        text: JSON.stringify(schemas, null, 2),
+                    }],
+                };
+            } catch (error: any) {
+                return {
+                    content: [{ type: "text" as const, text: `Error: ${error.response?.data?.error ?? error.message}` }],
+                    isError: true,
+                };
+            }
+        }
+    );
+
+    // ─── 2. Get a single collection schema ─────────────────
+
+    server.registerTool(
+        "get_collection_schema",
+        {
+            description: `Get the full schema definition for a specific collection, including all properties, 
+validation rules, display configuration, and subcollection definitions.`,
+            inputSchema: {
+                projectId: z.string().describe("Firebase project ID"),
+                collectionId: z.string().describe("Collection ID (usually same as the Firestore path, e.g., 'products')"),
+            },
+            annotations: { readOnlyHint: true },
+        },
+        async ({ projectId, collectionId }) => {
+            try {
+                await api.assertAdmin(projectId);
+                const schema = await api.getCollectionSchema(projectId, collectionId);
+                return {
+                    content: [{
+                        type: "text" as const,
+                        text: JSON.stringify(schema, null, 2),
+                    }],
+                };
+            } catch (error: any) {
+                return {
+                    content: [{ type: "text" as const, text: `Error: ${error.response?.data?.error ?? error.message}` }],
+                    isError: true,
+                };
+            }
+        }
+    );
+
+    // ─── 3. Save (create/replace) a collection schema ──────
+
+    server.registerTool(
+        "save_collection_schema",
+        {
+            description: `Create or fully replace a collection schema. This defines how a Firestore collection 
+is displayed and edited in FireCMS. Requires at minimum: id, path, and name. 
+
+Example schema:
+{
+  "id": "products",
+  "path": "products",
+  "name": "Products",
+  "singularName": "Product",
+  "icon": "ShoppingCart",
+  "description": "Product catalog",
+  "group": "Shop",
+  "properties": {
+    "name": { "dataType": "string", "name": "Name", "validation": { "required": true } },
+    "price": { "dataType": "number", "name": "Price", "validation": { "required": true, "min": 0 } },
+    "status": { "dataType": "string", "name": "Status", "enumValues": [
+      { "id": "draft", "label": "Draft" },
+      { "id": "published", "label": "Published" }
+    ]}
+  },
+  "propertiesOrder": ["name", "price", "status"]
+}`,
+            inputSchema: {
+                projectId: z.string().describe("Firebase project ID"),
+                collectionId: z.string().describe("Collection ID (e.g., 'products')"),
+                schema: z.object({
+                    path: z.string().describe("Firestore collection path"),
+                    name: z.string().describe("Display name for the collection"),
+                    singularName: z.string().optional().describe("Singular name (e.g., 'Product')"),
+                    description: z.string().optional().describe("Collection description"),
+                    icon: z.string().optional().describe("Material icon name (e.g., 'ShoppingCart')"),
+                    group: z.string().optional().describe("Navigation group name"),
+                    properties: z.record(PropertySchema).describe("Property definitions keyed by field name"),
+                    propertiesOrder: z.array(z.string()).optional().describe("Display order of properties"),
+                    defaultSize: z.enum(["xs", "s", "m", "l", "xl"]).optional().describe("Default row size in table"),
+                    initialSort: z.tuple([z.string(), z.enum(["asc", "desc"])]).optional().describe("Default sort [field, direction]"),
+                }).passthrough().describe("Complete collection schema definition"),
+            },
+        },
+        async ({ projectId, collectionId, schema }) => {
+            try {
+                await api.assertAdmin(projectId);
+                const fullSchema = { id: collectionId, ...schema };
+                const result = await api.saveCollectionSchema(projectId, collectionId, fullSchema);
+                return {
+                    content: [{
+                        type: "text" as const,
+                        text: `Collection schema "${collectionId}" saved successfully.\n\n${JSON.stringify(result, null, 2)}`,
+                    }],
+                };
+            } catch (error: any) {
+                return {
+                    content: [{ type: "text" as const, text: `Error: ${error.response?.data?.error ?? error.message}` }],
+                    isError: true,
+                };
+            }
+        }
+    );
+
+    // ─── 4. Update (partial) a collection schema ───────────
+
+    server.registerTool(
+        "update_collection_schema",
+        {
+            description: `Partially update an existing collection schema. Only the specified fields are modified 
+(merged with the existing schema). Use this for changes like renaming, updating the group, 
+changing display settings, or adding new properties.`,
+            inputSchema: {
+                projectId: z.string().describe("Firebase project ID"),
+                collectionId: z.string().describe("Collection ID to update"),
+                data: z.record(z.any()).describe("Fields to update (merged with existing schema)"),
+            },
+        },
+        async ({ projectId, collectionId, data }) => {
+            try {
+                await api.assertAdmin(projectId);
+                const result = await api.updateCollectionSchema(projectId, collectionId, data);
+                return {
+                    content: [{
+                        type: "text" as const,
+                        text: `Collection schema "${collectionId}" updated successfully.\n\n${JSON.stringify(result, null, 2)}`,
+                    }],
+                };
+            } catch (error: any) {
+                return {
+                    content: [{ type: "text" as const, text: `Error: ${error.response?.data?.error ?? error.message}` }],
+                    isError: true,
+                };
+            }
+        }
+    );
+
+    // ─── 5. Delete a collection schema ─────────────────────
+
+    server.registerTool(
+        "delete_collection_schema",
+        {
+            description: `Delete a collection schema from FireCMS. This removes the collection configuration 
+from the CMS — it does NOT delete the underlying Firestore data. The collection will simply 
+no longer appear in the FireCMS UI.`,
+            inputSchema: {
+                projectId: z.string().describe("Firebase project ID"),
+                collectionId: z.string().describe("Collection ID to delete"),
+            },
+            annotations: { destructiveHint: true },
+        },
+        async ({ projectId, collectionId }) => {
+            try {
+                await api.assertAdmin(projectId);
+                await api.deleteCollectionSchema(projectId, collectionId);
+                return {
+                    content: [{
+                        type: "text" as const,
+                        text: `Collection schema "${collectionId}" deleted successfully. Note: the underlying Firestore data was not affected.`,
+                    }],
+                };
+            } catch (error: any) {
+                return {
+                    content: [{ type: "text" as const, text: `Error: ${error.response?.data?.error ?? error.message}` }],
+                    isError: true,
+                };
+            }
+        }
+    );
+
+    // ─── 6. Save (add/update) a single property ────────────
+
+    server.registerTool(
+        "save_property",
+        {
+            description: `Add or update a single property in a collection schema. This is more granular than 
+updating the entire schema — use it when you want to add a new field or modify an existing 
+one without affecting other properties.
+
+Example property:
+{
+  "dataType": "string",
+  "name": "Description",
+  "description": "Product description",
+  "multiline": true,
+  "validation": { "required": true, "max": 500 }
+}`,
+            inputSchema: {
+                projectId: z.string().describe("Firebase project ID"),
+                collectionId: z.string().describe("Collection ID"),
+                propertyKey: z.string().describe("Property field key (e.g., 'description', 'price')"),
+                property: PropertySchema.describe("Property definition"),
+                namespace: z.string().optional().describe("Dot-separated namespace for nested properties in maps (e.g., 'address' for address.street)"),
+            },
+        },
+        async ({ projectId, collectionId, propertyKey, property, namespace }) => {
+            try {
+                await api.assertAdmin(projectId);
+                const result = await api.saveProperty(projectId, collectionId, propertyKey, property, namespace);
+                return {
+                    content: [{
+                        type: "text" as const,
+                        text: `Property "${propertyKey}" saved in collection "${collectionId}" successfully.\n\n${JSON.stringify(result, null, 2)}`,
+                    }],
+                };
+            } catch (error: any) {
+                return {
+                    content: [{ type: "text" as const, text: `Error: ${error.response?.data?.error ?? error.message}` }],
+                    isError: true,
+                };
+            }
+        }
+    );
+
+    // ─── 7. Delete a property ──────────────────────────────
+
+    server.registerTool(
+        "delete_property",
+        {
+            description: `Remove a property from a collection schema. This removes the field definition from 
+the CMS configuration — it does NOT delete the field from existing Firestore documents.`,
+            inputSchema: {
+                projectId: z.string().describe("Firebase project ID"),
+                collectionId: z.string().describe("Collection ID"),
+                propertyKey: z.string().describe("Property key to remove"),
+                namespace: z.string().optional().describe("Dot-separated namespace for nested properties"),
+            },
+            annotations: { destructiveHint: true },
+        },
+        async ({ projectId, collectionId, propertyKey, namespace }) => {
+            try {
+                await api.assertAdmin(projectId);
+                await api.deleteProperty(projectId, collectionId, propertyKey, namespace);
+                return {
+                    content: [{
+                        type: "text" as const,
+                        text: `Property "${propertyKey}" removed from collection "${collectionId}". Note: existing Firestore data was not affected.`,
+                    }],
+                };
+            } catch (error: any) {
+                return {
+                    content: [{ type: "text" as const, text: `Error: ${error.response?.data?.error ?? error.message}` }],
+                    isError: true,
+                };
+            }
+        }
+    );
+}

package/src/tools/import.ts

@@ -0,0 +1,65 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { FireCMSApiClient } from "../api-client.js";
+
+/**
+ * Register data import tools — bulk operations for Firestore documents.
+ * Admin-only operations.
+ */
+export function registerImportTools(server: McpServer, api: FireCMSApiClient) {
+
+    server.registerTool(
+        "import_documents",
+        {
+            description: `Bulk import documents into a Firestore collection. Useful for seeding data, 
+migrations, or restoring from a backup. Each document can optionally specify an ID; 
+if omitted, Firestore generates one. Use "merge: true" to update existing documents 
+instead of overwriting.
+
+Maximum 500 documents per call. For larger imports, call multiple times.`,
+            inputSchema: {
+                projectId: z.string().describe("Firebase project ID"),
+                collectionPath: z.string().describe("Target collection path (e.g., 'products')"),
+                documents: z.array(z.object({
+                    id: z.string().optional().describe("Optional document ID"),
+                    data: z.record(z.any()).describe("Document fields"),
+                })).describe("Array of documents to import (max 500)"),
+                merge: z.boolean().optional().describe("If true, merge with existing documents instead of overwriting (default: false)"),
+                databaseId: z.string().optional().describe("Firestore database ID (default: '(default)')"),
+            },
+        },
+        async ({ projectId, collectionPath, documents, merge, databaseId }) => {
+            try {
+                await api.assertAdmin(projectId);
+
+                if (documents.length > 500) {
+                    return {
+                        content: [{
+                            type: "text" as const,
+                            text: `Error: Maximum 500 documents per import call. You provided ${documents.length}. Split into batches.`,
+                        }],
+                        isError: true,
+                    };
+                }
+
+                const result = await api.importDocuments(projectId, {
+                    path: collectionPath,
+                    documents,
+                    merge: merge ?? false,
+                    databaseId,
+                });
+                return {
+                    content: [{
+                        type: "text" as const,
+                        text: `Successfully imported ${documents.length} document(s) into "${collectionPath}".\n\n${JSON.stringify(result, null, 2)}`,
+                    }],
+                };
+            } catch (error: any) {
+                return {
+                    content: [{ type: "text" as const, text: `Error importing: ${error.response?.data?.error ?? error.message}` }],
+                    isError: true,
+                };
+            }
+        }
+    );
+}

package/src/tools/project-config.ts

@@ -0,0 +1,202 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { FireCMSApiClient } from "../api-client.js";
+
+/**
+ * Register project configuration tools — manage project settings like
+ * name, colors, locale, feature toggles, etc. Admin-only operations.
+ */
+export function registerProjectConfigTools(server: McpServer, api: FireCMSApiClient) {
+
+    // ─── 1. Get project configuration ──────────────────────
+
+    server.registerTool(
+        "get_project_config",
+        {
+            description: `Get the full configuration for a FireCMS project, including:
+- Project name, logo, and brand colors (primary/secondary)
+- Subscription plan and trial status
+- Feature toggles (text search, entity history, App Check)
+- Default locale settings
+- Customization revision info`,
+            inputSchema: {
+                projectId: z.string().describe("Firebase project ID"),
+            },
+            annotations: { readOnlyHint: true },
+        },
+        async ({ projectId }) => {
+            try {
+                await api.assertAdmin(projectId);
+                const config = await api.getProjectConfig(projectId);
+                return {
+                    content: [{
+                        type: "text" as const,
+                        text: JSON.stringify(config, null, 2),
+                    }],
+                };
+            } catch (error: any) {
+                return {
+                    content: [{ type: "text" as const, text: `Error: ${error.response?.data?.error ?? error.message}` }],
+                    isError: true,
+                };
+            }
+        }
+    );
+
+    // ─── 2. Update project name ────────────────────────────
+
+    server.registerTool(
+        "update_project_name",
+        {
+            description: "Update the display name of a FireCMS project.",
+            inputSchema: {
+                projectId: z.string().describe("Firebase project ID"),
+                name: z.string().describe("New project name"),
+            },
+        },
+        async ({ projectId, name }) => {
+            try {
+                await api.assertAdmin(projectId);
+                await api.updateProjectConfig(projectId, { name });
+                return {
+                    content: [{
+                        type: "text" as const,
+                        text: `Project name updated to "${name}".`,
+                    }],
+                };
+            } catch (error: any) {
+                return {
+                    content: [{ type: "text" as const, text: `Error: ${error.response?.data?.error ?? error.message}` }],
+                    isError: true,
+                };
+            }
+        }
+    );
+
+    // ─── 3. Update brand colors ────────────────────────────
+
+    server.registerTool(
+        "update_project_colors",
+        {
+            description: "Update the primary and/or secondary brand colors for the CMS UI. Colors should be hex values (e.g., '#0070F4').",
+            inputSchema: {
+                projectId: z.string().describe("Firebase project ID"),
+                primaryColor: z.string().optional().describe("Primary color hex (e.g., '#0070F4')"),
+                secondaryColor: z.string().optional().describe("Secondary color hex (e.g., '#FF5B79')"),
+            },
+        },
+        async ({ projectId, primaryColor, secondaryColor }) => {
+            try {
+                await api.assertAdmin(projectId);
+                const data: Record<string, any> = {};
+                if (primaryColor) data.primary_color = primaryColor;
+                if (secondaryColor) data.secondary_color = secondaryColor;
+                await api.updateProjectConfig(projectId, data);
+                const parts: string[] = [];
+                if (primaryColor) parts.push(`primary → ${primaryColor}`);
+                if (secondaryColor) parts.push(`secondary → ${secondaryColor}`);
+                return {
+                    content: [{
+                        type: "text" as const,
+                        text: `Brand colors updated: ${parts.join(", ")}.`,
+                    }],
+                };
+            } catch (error: any) {
+                return {
+                    content: [{ type: "text" as const, text: `Error: ${error.response?.data?.error ?? error.message}` }],
+                    isError: true,
+                };
+            }
+        }
+    );
+
+    // ─── 4. Update default locale ──────────────────────────
+
+    server.registerTool(
+        "update_default_locale",
+        {
+            description: "Change the default locale for the CMS (affects date formatting, etc.).",
+            inputSchema: {
+                projectId: z.string().describe("Firebase project ID"),
+                locale: z.string().describe("Locale code (e.g., 'en', 'es', 'de', 'fr', 'it')"),
+            },
+        },
+        async ({ projectId, locale }) => {
+            try {
+                await api.assertAdmin(projectId);
+                await api.updateProjectConfig(projectId, { default_locale: locale });
+                return {
+                    content: [{
+                        type: "text" as const,
+                        text: `Default locale updated to "${locale}".`,
+                    }],
+                };
+            } catch (error: any) {
+                return {
+                    content: [{ type: "text" as const, text: `Error: ${error.response?.data?.error ?? error.message}` }],
+                    isError: true,
+                };
+            }
+        }
+    );
+
+    // ─── 5. Toggle text search ─────────────────────────────
+
+    server.registerTool(
+        "toggle_text_search",
+        {
+            description: "Enable or disable the local text search feature for a project.",
+            inputSchema: {
+                projectId: z.string().describe("Firebase project ID"),
+                enabled: z.boolean().describe("true to enable, false to disable"),
+            },
+        },
+        async ({ projectId, enabled }) => {
+            try {
+                await api.assertAdmin(projectId);
+                await api.updateProjectConfig(projectId, { local_text_search_enabled: enabled });
+                return {
+                    content: [{
+                        type: "text" as const,
+                        text: `Local text search ${enabled ? "enabled" : "disabled"}.`,
+                    }],
+                };
+            } catch (error: any) {
+                return {
+                    content: [{ type: "text" as const, text: `Error: ${error.response?.data?.error ?? error.message}` }],
+                    isError: true,
+                };
+            }
+        }
+    );
+
+    // ─── 6. Toggle entity history ──────────────────────────
+
+    server.registerTool(
+        "toggle_entity_history",
+        {
+            description: "Enable or disable entity history tracking (audit log of document changes) for a project.",
+            inputSchema: {
+                projectId: z.string().describe("Firebase project ID"),
+                enabled: z.boolean().describe("true to enable, false to disable"),
+            },
+        },
+        async ({ projectId, enabled }) => {
+            try {
+                await api.assertAdmin(projectId);
+                await api.updateProjectConfig(projectId, { history_default_enabled: enabled });
+                return {
+                    content: [{
+                        type: "text" as const,
+                        text: `Entity history tracking ${enabled ? "enabled" : "disabled"}.`,
+                    }],
+                };
+            } catch (error: any) {
+                return {
+                    content: [{ type: "text" as const, text: `Error: ${error.response?.data?.error ?? error.message}` }],
+                    isError: true,
+                };
+            }
+        }
+    );
+}

package/src/tools/users.ts

@@ -4,6 +4,8 @@ import { FireCMSApiClient } from "../api-client.js";
 
 /**
  * Register user management tools.
+ * Read operations are available to all authenticated users.
+ * Write operations (add, update, remove) are admin-only.
  */
 export function registerUserTools(server: McpServer, api: FireCMSApiClient) {
 
@@ -14,6 +16,7 @@ export function registerUserTools(server: McpServer, api: FireCMSApiClient) {
             inputSchema: {
                 projectId: z.string().describe("The Firebase project ID"),
             },
+            annotations: { readOnlyHint: true },
         },
         async ({ projectId }) => {
             try {
@@ -28,7 +31,7 @@ export function registerUserTools(server: McpServer, api: FireCMSApiClient) {
     server.registerTool(
         "add_user",
         {
-            description: "Invite a new user to a FireCMS project. Sends an invitation email.",
+            description: "Invite a new user to a FireCMS project. Sends an invitation email. Admin-only.",
             inputSchema: {
                 projectId: z.string().describe("The Firebase project ID"),
                 email: z.string().email().describe("Email address of the user to invite"),
@@ -37,6 +40,7 @@ export function registerUserTools(server: McpServer, api: FireCMSApiClient) {
         },
         async ({ projectId, email, roles }) => {
             try {
+                await api.assertAdmin(projectId);
                 const result = await api.createUser(projectId, email, roles);
                 return {
                     content: [{ type: "text" as const, text: `Invited ${email} with roles: ${roles.join(", ")}\n\n${JSON.stringify(result, null, 2)}` }],
@@ -50,7 +54,7 @@ export function registerUserTools(server: McpServer, api: FireCMSApiClient) {
     server.registerTool(
         "update_user_roles",
         {
-            description: "Update the roles of an existing user in a FireCMS project",
+            description: "Update the roles of an existing user in a FireCMS project. Admin-only.",
             inputSchema: {
                 projectId: z.string().describe("The Firebase project ID"),
                 userId: z.string().describe("The user ID to update"),
@@ -59,6 +63,7 @@ export function registerUserTools(server: McpServer, api: FireCMSApiClient) {
         },
         async ({ projectId, userId, roles }) => {
             try {
+                await api.assertAdmin(projectId);
                 const result = await api.updateUser(projectId, userId, roles);
                 return {
                     content: [{ type: "text" as const, text: `Updated user ${userId} roles to: ${roles.join(", ")}\n\n${JSON.stringify(result, null, 2)}` }],
@@ -72,14 +77,16 @@ export function registerUserTools(server: McpServer, api: FireCMSApiClient) {
     server.registerTool(
         "remove_user",
         {
-            description: "Remove a user from a FireCMS project, revoking their access",
+            description: "Remove a user from a FireCMS project, revoking their access. Admin-only.",
             inputSchema: {
                 projectId: z.string().describe("The Firebase project ID"),
                 userId: z.string().describe("The user ID to remove"),
             },
+            annotations: { destructiveHint: true },
         },
         async ({ projectId, userId }) => {
             try {
+                await api.assertAdmin(projectId);
                 const result = await api.deleteUser(projectId, userId);
                 return {
                     content: [{ type: "text" as const, text: `Removed user ${userId}\n\n${JSON.stringify(result, null, 2)}` }],

package/LICENSE

@@ -1,6 +0,0 @@
-Source code in this repository is variously licensed under the Business Source
-License 1.1 (BSL), Apache version 2.0 and the MIT license. A copy of each
-license can be found in each one of the packages under the folder packages
-under a file called License. Source code in a given file is licensed under the
-BSL and the copyright belongs to Firecms Authors unless otherwise noted at the
-beginning of the file.