@centrali-io/centrali-mcp 1.0.0

package/dist/tools/structures.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { CentraliSDK } from "@centrali-io/centrali-sdk";
+export declare function registerStructureTools(server: McpServer, sdk: CentraliSDK): void;

package/dist/tools/structures.js

@@ -0,0 +1,64 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerStructureTools = registerStructureTools;
+const zod_1 = require("zod");
+function registerStructureTools(server, sdk) {
+    server.tool("list_structures", "List all data structures (schemas) in the Centrali workspace. Returns name, slug, description, and property definitions for each structure.", {
+        page: zod_1.z.number().optional().describe("Page number (1-indexed)"),
+        limit: zod_1.z.number().optional().describe("Results per page"),
+    }, (_a) => __awaiter(this, [_a], void 0, function* ({ page, limit }) {
+        try {
+            const result = yield sdk.structures.list({ page, limit });
+            return {
+                content: [
+                    { type: "text", text: JSON.stringify(result.data, null, 2) },
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Error listing structures: ${error.message}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    }));
+    server.tool("get_structure", "Get the full schema definition for a specific structure by its record slug. Returns properties, types, constraints, and configuration.", {
+        recordSlug: zod_1.z
+            .string()
+            .describe("The structure's record slug (e.g., 'orders', 'customers')"),
+    }, (_a) => __awaiter(this, [_a], void 0, function* ({ recordSlug }) {
+        try {
+            const result = yield sdk.structures.getBySlug(recordSlug);
+            return {
+                content: [
+                    { type: "text", text: JSON.stringify(result.data, null, 2) },
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Error getting structure '${recordSlug}': ${error.message}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    }));
+}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@centrali-io/centrali-mcp",
+  "version": "1.0.0",
+  "description": "Centrali MCP Server - AI assistant integration for Centrali workspaces",
+  "main": "dist/index.js",
+  "type": "commonjs",
+  "bin": {
+    "centrali-mcp": "./dist/index.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/blueinit/centrali-mcp.git"
+  },
+  "scripts": {
+    "build": "tsc --project tsconfig.json",
+    "prepublishOnly": "npm run build",
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": ["mcp", "centrali", "ai", "model-context-protocol"],
+  "author": "Blueinit",
+  "license": "ISC",
+  "dependencies": {
+    "@centrali-io/centrali-sdk": "^3.1.0",
+    "@modelcontextprotocol/sdk": "^1.12.1"
+  },
+  "devDependencies": {
+    "typescript": "^5.8.3"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  }
+}

package/src/index.ts

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CentraliSDK } from "@centrali-io/centrali-sdk";
+import { registerStructureTools } from "./tools/structures.js";
+import { registerRecordTools } from "./tools/records.js";
+import { registerSearchTools } from "./tools/search.js";
+import { registerComputeTools } from "./tools/compute.js";
+import { registerSmartQueryTools } from "./tools/smart-queries.js";
+import { registerStructureResources } from "./resources/structures.js";
+
+function getRequiredEnv(name: string): string {
+  const value = process.env[name];
+  if (!value) {
+    console.error(`Missing required environment variable: ${name}`);
+    process.exit(1);
+  }
+  return value;
+}
+
+async function main() {
+  const baseUrl = getRequiredEnv("CENTRALI_URL");
+  const clientId = getRequiredEnv("CENTRALI_CLIENT_ID");
+  const clientSecret = getRequiredEnv("CENTRALI_CLIENT_SECRET");
+  const workspaceId = getRequiredEnv("CENTRALI_WORKSPACE");
+
+  const sdk = new CentraliSDK({
+    baseUrl,
+    workspaceId,
+    clientId,
+    clientSecret,
+  });
+
+  const server = new McpServer({
+    name: "centrali",
+    version: "1.0.0",
+  });
+
+  // Register all tools
+  registerStructureTools(server, sdk);
+  registerRecordTools(server, sdk);
+  registerSearchTools(server, sdk);
+  registerComputeTools(server, sdk);
+  registerSmartQueryTools(server, sdk);
+
+  // Register resources
+  registerStructureResources(server, sdk);
+
+  // Start stdio transport
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+
+main().catch((error) => {
+  console.error("Fatal error:", error);
+  process.exit(1);
+});

package/src/resources/structures.ts

@@ -0,0 +1,71 @@
+import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { CentraliSDK } from "@centrali-io/centrali-sdk";
+
+export function registerStructureResources(
+  server: McpServer,
+  sdk: CentraliSDK
+) {
+  // Static resource: list all structures (gives LLM workspace context)
+  server.resource(
+    "structures-list",
+    "centrali://structures",
+    {
+      description:
+        "List of all data structures in the workspace with name, slug, and description",
+      mimeType: "application/json",
+    },
+    async (uri) => {
+      const result = await sdk.structures.list({ limit: 100 });
+      const summary = (result.data || []).map((s) => ({
+        name: s.name,
+        recordSlug: s.recordSlug,
+        description: s.description || "",
+        propertyCount: s.properties?.length || 0,
+        status: s.status,
+      }));
+      return {
+        contents: [
+          {
+            uri: uri.href,
+            mimeType: "application/json",
+            text: JSON.stringify(summary, null, 2),
+          },
+        ],
+      };
+    }
+  );
+
+  // Resource template: full schema for a specific structure
+  server.resource(
+    "structure-schema",
+    new ResourceTemplate("centrali://structures/{slug}", {
+      list: async () => {
+        const result = await sdk.structures.list({ limit: 100 });
+        return {
+          resources: (result.data || []).map((s) => ({
+            uri: `centrali://structures/${s.recordSlug}`,
+            name: s.name,
+            description: s.description || `Schema for ${s.name}`,
+            mimeType: "application/json",
+          })),
+        };
+      },
+    }),
+    {
+      description: "Full schema definition for a specific structure",
+      mimeType: "application/json",
+    },
+    async (uri, { slug }) => {
+      const result = await sdk.structures.getBySlug(slug as string);
+      return {
+        contents: [
+          {
+            uri: uri.href,
+            mimeType: "application/json",
+            text: JSON.stringify(result.data, null, 2),
+          },
+        ],
+      };
+    }
+  );
+}

package/src/tools/compute.ts

@@ -0,0 +1,120 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { CentraliSDK } from "@centrali-io/centrali-sdk";
+import { z } from "zod";
+
+export function registerComputeTools(server: McpServer, sdk: CentraliSDK) {
+  server.tool(
+    "list_functions",
+    "List all compute functions in the workspace. Compute functions are JavaScript code blocks that run server-side.",
+    {
+      page: z.number().optional().describe("Page number"),
+      limit: z.number().optional().describe("Results per page"),
+    },
+    async ({ page, limit }) => {
+      try {
+        const options: Record<string, any> = {};
+        if (page !== undefined) options.page = page;
+        if (limit !== undefined) options.limit = limit;
+
+        const result = await sdk.functions.list(
+          Object.keys(options).length > 0 ? options : undefined
+        );
+        return {
+          content: [
+            { type: "text", text: JSON.stringify(result.data, null, 2) },
+          ],
+        };
+      } catch (error: any) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Error listing functions: ${error.message}`,
+            },
+          ],
+          isError: true,
+        };
+      }
+    }
+  );
+
+  server.tool(
+    "list_triggers",
+    "List function triggers in the workspace. Triggers define how and when compute functions are executed (on-demand, event-driven, scheduled, webhook).",
+    {
+      executionType: z
+        .enum(["on-demand", "event-driven", "scheduled", "webhook"])
+        .optional()
+        .describe("Filter by trigger execution type"),
+      page: z.number().optional().describe("Page number"),
+      limit: z.number().optional().describe("Results per page"),
+    },
+    async ({ executionType, page, limit }) => {
+      try {
+        const options: Record<string, any> = {};
+        if (executionType) options.executionType = executionType;
+        if (page !== undefined) options.page = page;
+        if (limit !== undefined) options.limit = limit;
+
+        const result = await sdk.triggers.listAll(
+          Object.keys(options).length > 0 ? options : undefined
+        );
+        return {
+          content: [
+            { type: "text", text: JSON.stringify(result.data, null, 2) },
+          ],
+        };
+      } catch (error: any) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Error listing triggers: ${error.message}`,
+            },
+          ],
+          isError: true,
+        };
+      }
+    }
+  );
+
+  server.tool(
+    "invoke_trigger",
+    "Invoke an on-demand function trigger by ID. Optionally pass a custom payload. Returns the queued job ID.",
+    {
+      triggerId: z.string().describe("The trigger ID (UUID) to invoke"),
+      payload: z
+        .record(z.string(), z.any())
+        .optional()
+        .describe("Custom payload to pass to the function execution"),
+    },
+    async ({ triggerId, payload }) => {
+      try {
+        const options = payload ? { payload } : undefined;
+        const result = await sdk.triggers.invoke(triggerId, options);
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(
+                { jobId: result.data, message: "Trigger invoked successfully" },
+                null,
+                2
+              ),
+            },
+          ],
+        };
+      } catch (error: any) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Error invoking trigger '${triggerId}': ${error.message}`,
+            },
+          ],
+          isError: true,
+        };
+      }
+    }
+  );
+}

package/src/tools/records.ts

@@ -0,0 +1,209 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { CentraliSDK } from "@centrali-io/centrali-sdk";
+import { z } from "zod";
+
+export function registerRecordTools(server: McpServer, sdk: CentraliSDK) {
+  server.tool(
+    "query_records",
+    "Query records from a structure with optional filters, sorting, and pagination. Filters use 'data.' prefix for custom fields and bracket notation for operators (e.g., 'data.status': 'active', 'data.price[lte]': 100).",
+    {
+      recordSlug: z
+        .string()
+        .describe("The structure's record slug (e.g., 'orders')"),
+      filters: z
+        .record(z.string(), z.any())
+        .optional()
+        .describe(
+          "Filter object with keys like 'data.fieldName' or 'data.fieldName[operator]'. Operators: eq, ne, gt, gte, lt, lte, in, nin, contains, startswith, endswith"
+        ),
+      sort: z
+        .string()
+        .optional()
+        .describe(
+          "Sort field with optional '-' prefix for descending (e.g., '-createdAt')"
+        ),
+      page: z.number().optional().describe("Page number (1-indexed, default: 1)"),
+      pageSize: z
+        .number()
+        .optional()
+        .describe("Records per page (default: 50, max: 500)"),
+      expand: z
+        .string()
+        .optional()
+        .describe(
+          "Comma-separated reference fields to expand (e.g., 'customer,product')"
+        ),
+    },
+    async ({ recordSlug, filters, sort, page, pageSize, expand }) => {
+      try {
+        const params: Record<string, any> = {
+          ...filters,
+          sort,
+          page,
+          pageSize,
+          expand,
+        };
+        // Remove undefined values
+        Object.keys(params).forEach(
+          (key) => params[key] === undefined && delete params[key]
+        );
+
+        const result = await sdk.queryRecords(recordSlug, params);
+        return {
+          content: [
+            { type: "text", text: JSON.stringify(result, null, 2) },
+          ],
+        };
+      } catch (error: any) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Error querying records from '${recordSlug}': ${error.message}`,
+            },
+          ],
+          isError: true,
+        };
+      }
+    }
+  );
+
+  server.tool(
+    "get_record",
+    "Get a single record by its ID from a structure. Optionally expand reference fields.",
+    {
+      recordSlug: z.string().describe("The structure's record slug"),
+      id: z.string().describe("The record ID (UUID)"),
+      expand: z
+        .string()
+        .optional()
+        .describe("Comma-separated reference fields to expand"),
+    },
+    async ({ recordSlug, id, expand }) => {
+      try {
+        const options = expand ? { expand } : undefined;
+        const result = await sdk.getRecord(recordSlug, id, options);
+        return {
+          content: [
+            { type: "text", text: JSON.stringify(result.data, null, 2) },
+          ],
+        };
+      } catch (error: any) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Error getting record '${id}' from '${recordSlug}': ${error.message}`,
+            },
+          ],
+          isError: true,
+        };
+      }
+    }
+  );
+
+  server.tool(
+    "create_record",
+    "Create a new record in a structure. Pass the record data as a JSON object with field names matching the structure's properties.",
+    {
+      recordSlug: z
+        .string()
+        .describe("The structure's record slug (e.g., 'orders')"),
+      data: z
+        .record(z.string(), z.any())
+        .describe("The record data object (field names as keys)"),
+    },
+    async ({ recordSlug, data }) => {
+      try {
+        const result = await sdk.createRecord(recordSlug, data);
+        return {
+          content: [
+            { type: "text", text: JSON.stringify(result.data, null, 2) },
+          ],
+        };
+      } catch (error: any) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Error creating record in '${recordSlug}': ${error.message}`,
+            },
+          ],
+          isError: true,
+        };
+      }
+    }
+  );
+
+  server.tool(
+    "update_record",
+    "Update an existing record by ID. Only include the fields you want to change.",
+    {
+      recordSlug: z.string().describe("The structure's record slug"),
+      id: z.string().describe("The record ID (UUID) to update"),
+      data: z
+        .record(z.string(), z.any())
+        .describe("Object with fields to update (partial update)"),
+    },
+    async ({ recordSlug, id, data }) => {
+      try {
+        const result = await sdk.updateRecord(recordSlug, id, data);
+        return {
+          content: [
+            { type: "text", text: JSON.stringify(result.data, null, 2) },
+          ],
+        };
+      } catch (error: any) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Error updating record '${id}' in '${recordSlug}': ${error.message}`,
+            },
+          ],
+          isError: true,
+        };
+      }
+    }
+  );
+
+  server.tool(
+    "delete_record",
+    "Delete a record by ID. Performs a soft delete by default (can be restored). Set hard=true for permanent deletion.",
+    {
+      recordSlug: z.string().describe("The structure's record slug"),
+      id: z.string().describe("The record ID (UUID) to delete"),
+      hard: z
+        .boolean()
+        .optional()
+        .describe(
+          "If true, permanently delete. Default: false (soft delete, can be restored)"
+        ),
+    },
+    async ({ recordSlug, id, hard }) => {
+      try {
+        const options = hard !== undefined ? { hard } : undefined;
+        await sdk.deleteRecord(recordSlug, id, options);
+        const deleteType = hard ? "permanently deleted" : "soft-deleted";
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Record '${id}' ${deleteType} from '${recordSlug}'.`,
+            },
+          ],
+        };
+      } catch (error: any) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Error deleting record '${id}' from '${recordSlug}': ${error.message}`,
+            },
+          ],
+          isError: true,
+        };
+      }
+    }
+  );
+}

package/src/tools/search.ts

@@ -0,0 +1,50 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { CentraliSDK } from "@centrali-io/centrali-sdk";
+import { z } from "zod";
+
+export function registerSearchTools(server: McpServer, sdk: CentraliSDK) {
+  server.tool(
+    "search_records",
+    "Full-text search across records in the workspace. Powered by Meilisearch. Optionally filter by structure(s) and limit results.",
+    {
+      query: z.string().describe("The search query string"),
+      structures: z
+        .union([z.string(), z.array(z.string())])
+        .optional()
+        .describe(
+          "Filter by structure slug(s). Single slug string or array of slugs"
+        ),
+      limit: z
+        .number()
+        .optional()
+        .describe("Maximum results to return (default: 20, max: 100)"),
+    },
+    async ({ query, structures, limit }) => {
+      try {
+        const options: { structures?: string | string[]; limit?: number } = {};
+        if (structures) options.structures = structures;
+        if (limit) options.limit = limit;
+
+        const result = await sdk.search(
+          query,
+          Object.keys(options).length > 0 ? options : undefined
+        );
+        return {
+          content: [
+            { type: "text", text: JSON.stringify(result.data, null, 2) },
+          ],
+        };
+      } catch (error: any) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Error searching records: ${error.message}`,
+            },
+          ],
+          isError: true,
+        };
+      }
+    }
+  );
+}

package/src/tools/smart-queries.ts

@@ -0,0 +1,82 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { CentraliSDK } from "@centrali-io/centrali-sdk";
+import { z } from "zod";
+
+export function registerSmartQueryTools(server: McpServer, sdk: CentraliSDK) {
+  server.tool(
+    "list_smart_queries",
+    "List smart queries. Smart queries are reusable, parameterized queries defined in the Centrali console. Optionally filter by structure slug.",
+    {
+      recordSlug: z
+        .string()
+        .optional()
+        .describe(
+          "Filter by structure slug. If omitted, lists all smart queries in the workspace"
+        ),
+    },
+    async ({ recordSlug }) => {
+      try {
+        const result = recordSlug
+          ? await sdk.smartQueries.list(recordSlug)
+          : await sdk.smartQueries.listAll();
+        return {
+          content: [
+            { type: "text", text: JSON.stringify(result.data, null, 2) },
+          ],
+        };
+      } catch (error: any) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Error listing smart queries: ${error.message}`,
+            },
+          ],
+          isError: true,
+        };
+      }
+    }
+  );
+
+  server.tool(
+    "execute_smart_query",
+    "Execute a smart query by ID and return the results. Smart queries can have parameterized variables using {{variableName}} syntax.",
+    {
+      recordSlug: z
+        .string()
+        .describe("The structure's record slug the query belongs to"),
+      queryId: z.string().describe("The smart query ID (UUID) to execute"),
+      variables: z
+        .record(z.string(), z.string())
+        .optional()
+        .describe(
+          "Variables to substitute in the query (key-value pairs matching {{variableName}} placeholders)"
+        ),
+    },
+    async ({ recordSlug, queryId, variables }) => {
+      try {
+        const options = variables ? { variables } : undefined;
+        const result = await sdk.smartQueries.execute(
+          recordSlug,
+          queryId,
+          options
+        );
+        return {
+          content: [
+            { type: "text", text: JSON.stringify(result.data, null, 2) },
+          ],
+        };
+      } catch (error: any) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Error executing smart query '${queryId}': ${error.message}`,
+            },
+          ],
+          isError: true,
+        };
+      }
+    }
+  );
+}