meebly-onboarding-mcp-server 0.0.1

package/README.md

@@ -0,0 +1,31 @@
+# Meebly Onboarding MCP Server
+
+MCP Server for the Meebly AI platform, enabling agent and tool orchestration via the Model Context Protocol (MCP).
+
+## Tools
+
+This server exposes a set of MCP tools for agent and workflow management. Tools include:
+
+- `create_agent`: Create a new agent
+- `create_action`: Create a new API action
+
+Each tool has a defined input schema and returns structured results.
+
+## Setup
+
+```json
+{
+  "type": "stdio",
+  "command": "npx",
+  "args": ["-y", "@meebly/meebly-onboarding-mcp-server"],
+  "env": {
+    "MEEBLY_API_KEY": "YOUR_API_KEY"
+  }
+}
+```
+
+## Environment Variables
+
+Set the following environment variables:
+
+- `MEEBLY_API_KEY` — API key to your environment

package/dist/mcp-server/src/helpers/httpClient.js

@@ -0,0 +1,13 @@
+import axios from 'axios';
+// For development, it can read from env var to point to local server
+// In production, it will point to the deployed Meebly Backend because the env var will be undefined
+const baseUrl = (process.env.MEEBLY_BACKEND_URL || 'https://api.meebly.ai') + '/v1';
+// Client will set
+const apiKey = process.env.MEEBLY_API_KEY || '';
+export const httpClient = axios.create({
+    baseURL: baseUrl,
+    validateStatus: () => true, // never throw when not 2XX
+    headers: {
+        'X-API-Key': apiKey,
+    },
+});

package/dist/mcp-server/src/helpers/toolHelper.js

@@ -0,0 +1,24 @@
+/**
+ *  Helper function to maintain consistent tool return structure for success, failure, and error cases.
+ */
+export function toolSuccess(response, structuredContent) {
+    return toolReturn(`Operation performed successfully.\n${JSON.stringify(response.data, null, 2)}`, structuredContent);
+}
+export function toolFailure(response) {
+    return toolReturn(`Operation failed. Status: ${response.status}\nResponse: ${JSON.stringify(response.data, null, 2)}`);
+}
+export function toolError(error) {
+    return toolReturn(`Error occurred while performing operation: ${error}`);
+}
+// Helper function to format tool return messages in proper structure
+function toolReturn(message, structuredContent) {
+    return {
+        content: [
+            {
+                type: 'text',
+                text: message,
+            },
+        ],
+        structuredContent: structuredContent,
+    };
+}

package/dist/mcp-server/src/index.js

@@ -0,0 +1,27 @@
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+// Import all tools and resources
+import * as tools from './tools/index.js';
+import * as resources from './resources/index.js';
+// Create the MCP server instance
+const server = new McpServer({
+    name: 'meebly-onboarding-mcp-server',
+    version: '0.0.1',
+});
+// Register the tools
+Object.values(tools).forEach((tool) => {
+    server.registerTool(tool.name, {
+        description: tool.description,
+        inputSchema: tool.inputSchema,
+        outputSchema: tool.outputSchema,
+    }, tool.handler);
+});
+// Register the resources
+Object.values(resources).forEach((resource) => {
+    server.registerResource(resource.name, resource.uri, resource.metadata, resource.read);
+});
+// Start listening over stdio
+const transport = new StdioServerTransport();
+await server.connect(transport);
+// Keep process alive
+process.stdin.resume();

package/dist/mcp-server/src/resources/createActionEndpoint.js

@@ -0,0 +1,45 @@
+import { V1ActionDataSchema } from '../../../src/utils/validation.js';
+import { zodToJsonSchema } from 'zod-to-json-schema';
+const actionJsonSchema = zodToJsonSchema(V1ActionDataSchema, 'V1ActionDataSchema');
+const responseSchema = {
+    type: 'object',
+    properties: {
+        status: {
+            type: 'string',
+            description: 'Result status',
+        },
+        agent: actionJsonSchema,
+    },
+    required: ['status', 'agent'],
+};
+/**
+ * Resource describing the createAgent POST endpoint
+ */
+export const createActionEndpointResource = {
+    name: 'createActionEndpoint',
+    uri: 'api://meebly/action/create',
+    metadata: {
+        description: 'Describes the POST /action endpoint used to create new actions',
+        title: 'Create Action Endpoint',
+    },
+    read: async () => {
+        return {
+            contents: [
+                {
+                    uri: 'api://meebly/action/create',
+                    text: `
+POST /action
+
+Creates a new action.
+
+Request body schema (JSON Schema):
+${JSON.stringify(actionJsonSchema, null, 2)}
+
+Response schema (JSON Schema):
+${JSON.stringify(responseSchema, null, 2)}
+          `.trim(),
+                },
+            ],
+        };
+    },
+};

package/dist/mcp-server/src/resources/createAgentEndpoint.js

@@ -0,0 +1,45 @@
+import { AgentDataSchema } from '../../../src/utils/validation.js';
+import { zodToJsonSchema } from 'zod-to-json-schema';
+const agentJsonSchema = zodToJsonSchema(AgentDataSchema, 'AgentDataSchema');
+const responseSchema = {
+    type: 'object',
+    properties: {
+        status: {
+            type: 'string',
+            description: 'Result status',
+        },
+        agent: agentJsonSchema,
+    },
+    required: ['status', 'agent'],
+};
+/**
+ * Resource describing the createAgent POST endpoint
+ */
+export const createAgentEndpointResource = {
+    name: 'createAgentEndpoint',
+    uri: 'api://meebly/agent/create',
+    metadata: {
+        description: 'Describes the POST /agent endpoint used to create new agents',
+        title: 'Create Agent Endpoint',
+    },
+    read: async () => {
+        return {
+            contents: [
+                {
+                    uri: 'api://meebly/agent/create',
+                    text: `
+POST /agent
+
+Creates a new agent.
+
+Request body schema (JSON Schema):
+${JSON.stringify(agentJsonSchema, null, 2)}
+
+Response schema (JSON Schema):
+${JSON.stringify(responseSchema, null, 2)}
+          `.trim(),
+                },
+            ],
+        };
+    },
+};

package/dist/mcp-server/src/resources/index.js

@@ -0,0 +1,3 @@
+export { createActionEndpointResource } from './createActionEndpoint.js';
+export { createAgentEndpointResource } from './createAgentEndpoint.js';
+// add new resources here as you create them

package/dist/mcp-server/src/tools/createAction.js

@@ -0,0 +1,31 @@
+import { V1ActionDataSchema } from '../../../src/utils/validation.js';
+import { httpClient } from '../helpers/httpClient.js';
+import { toolSuccess, toolFailure, toolError } from '../helpers/toolHelper.js';
+import { z } from 'zod';
+const CreateActionOutputSchema = z.object({
+    id: z.string().describe('The unique identifier of the created action'),
+    name: z.string().describe('The name of the created action'),
+});
+export const CreateActionTool = {
+    name: 'create_action',
+    description: 'Create a new action using the POST /action endpoint',
+    inputSchema: V1ActionDataSchema,
+    outputSchema: CreateActionOutputSchema,
+    handler: async (actionData) => {
+        const createData = V1ActionDataSchema.parse(actionData);
+        try {
+            const response = await httpClient.post('/action', createData);
+            if (response.status !== 201) {
+                return toolFailure(response);
+            }
+            const outputData = {
+                id: response.data.id,
+                name: response.data.operationName,
+            };
+            return toolSuccess(response, outputData);
+        }
+        catch (error) {
+            return toolError(error);
+        }
+    },
+};

package/dist/mcp-server/src/tools/createAgent.js

@@ -0,0 +1,31 @@
+import { AgentDataSchema } from '../../../src/utils/validation.js';
+import { httpClient } from '../helpers/httpClient.js';
+import { toolSuccess, toolFailure, toolError } from '../helpers/toolHelper.js';
+import { z } from 'zod';
+const CreateAgentOutputSchema = z.object({
+    id: z.string().describe('The unique identifier of the created agent'),
+    name: z.string().describe('The name of the created agent'),
+});
+export const CreateAgentTool = {
+    name: 'create_agent',
+    description: 'Create a new agent using the POST /agent endpoint',
+    inputSchema: AgentDataSchema,
+    outputSchema: CreateAgentOutputSchema,
+    handler: async (agentData) => {
+        const createData = AgentDataSchema.parse(agentData);
+        try {
+            const response = await httpClient.post('/agent', createData);
+            if (response.status !== 201) {
+                return toolFailure(response);
+            }
+            const outputData = {
+                id: response.data.id,
+                name: response.data.name,
+            };
+            return toolSuccess(response, outputData);
+        }
+        catch (error) {
+            return toolError(error);
+        }
+    },
+};

package/dist/mcp-server/src/tools/index.js

@@ -0,0 +1,3 @@
+export { CreateAgentTool } from './createAgent.js';
+export { CreateActionTool } from './createAction.js';
+// add new tools here as you create them

package/dist/src/constants/index.js

@@ -0,0 +1,46 @@
+/**
+ * Application constants
+ */
+// Mastra storage and vector IDs
+export { MASTRA_STORAGE_IDS } from './mastraIds.js';
+// Supabase error codes
+export const SUPABASE_ERROR_CODES = {
+    NOT_FOUND: 'PGRST116',
+    DUPLICATE_KEY: '23505',
+    FOREIGN_KEY_VIOLATION: '23503',
+    NOT_NULL_VIOLATION: '23502',
+};
+// HTTP status codes
+export const HTTP_STATUS = {
+    OK: 200,
+    CREATED: 201,
+    BAD_REQUEST: 400,
+    UNAUTHORIZED: 401,
+    FORBIDDEN: 403,
+    NOT_FOUND: 404,
+    CONFLICT: 409,
+    INTERNAL_SERVER_ERROR: 500,
+    BAD_GATEWAY: 502,
+    TOO_MANY_REQUESTS: 429,
+};
+// Auth types
+export const STATIC_AUTH_TYPES = {
+    BEARER: 'bearer',
+    API_KEY: 'api-key',
+    ACCESS_TOKEN: 'access-token',
+};
+// Content types
+export const CONTENT_TYPES = {
+    JSON: 'application/json',
+    FORM_DATA: 'multipart/form-data',
+    FORM_URLENCODED: 'application/x-www-form-urlencoded',
+    TEXT_PLAIN: 'text/plain',
+};
+// HTTP methods
+export const HTTP_METHODS = {
+    GET: 'GET',
+    POST: 'POST',
+    PUT: 'PUT',
+    DELETE: 'DELETE',
+    PATCH: 'PATCH',
+};

package/dist/src/constants/mastraIds.js

@@ -0,0 +1,13 @@
+/**
+ * Mastra Storage and Vector Store IDs
+ *
+ * Centralized IDs for Mastra storage and vector instances.
+ * These IDs are required by Mastra v1 for tracking and managing
+ * storage instances within the framework.
+ */
+export const MASTRA_STORAGE_IDS = {
+    /** Main PostgreSQL storage instance */
+    POSTGRES_STORE: 'meebly-postgres-store',
+    /** PostgreSQL vector store instance */
+    PG_VECTOR: 'meebly-pg-vector',
+};

package/dist/src/utils/errorUtils.js

@@ -0,0 +1,104 @@
+import { HTTP_STATUS } from '../constants/index.js';
+/**
+ * Custom error class for API errors with error codes
+ */
+export class ApiError extends Error {
+    statusCode;
+    code;
+    details;
+    constructor(message, statusCode = HTTP_STATUS.INTERNAL_SERVER_ERROR, details, code) {
+        super(message);
+        this.name = 'ApiError';
+        this.statusCode = statusCode;
+        this.details = details;
+        this.code = code || ApiError.generateErrorCode(statusCode);
+        // Maintains proper stack trace for where our error was thrown (only available on V8)
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, ApiError);
+        }
+    }
+    /**
+     * Generate error code from HTTP status code
+     */
+    static generateErrorCode(statusCode) {
+        const codeMap = {
+            400: 'BAD_REQUEST',
+            401: 'UNAUTHORIZED',
+            403: 'FORBIDDEN',
+            404: 'NOT_FOUND',
+            409: 'CONFLICT',
+            422: 'VALIDATION_ERROR',
+            429: 'TOO_MANY_REQUESTS',
+            500: 'INTERNAL_SERVER_ERROR',
+            503: 'SERVICE_UNAVAILABLE',
+        };
+        return codeMap[statusCode] || 'UNKNOWN_ERROR';
+    }
+}
+/**
+ * Creates a standardized error response object
+ * @param error - The error object or message
+ * @param statusCode - HTTP status code
+ * @returns Standardized error response
+ */
+export function createErrorResponse(error, statusCode = HTTP_STATUS.INTERNAL_SERVER_ERROR) {
+    if (error instanceof ApiError) {
+        return {
+            error: error.message,
+            statusCode: error.statusCode,
+            details: error.details,
+        };
+    }
+    if (error instanceof Error) {
+        return {
+            error: error.message,
+            statusCode,
+        };
+    }
+    return {
+        error: typeof error === 'string' ? error : 'An unknown error occurred',
+        statusCode,
+    };
+}
+/**
+ * Handles async route errors for Express
+ * @param fn - Async route handler function
+ * @returns Express middleware function
+ */
+export function asyncErrorHandler(fn) {
+    return (req, res, next) => {
+        Promise.resolve(fn(req, res, next)).catch(next);
+    };
+}
+/**
+ * Express error middleware - Returns standardized error format
+ * @param err - Error object
+ * @param req - Express request
+ * @param res - Express response
+ * @param next - Express next function
+ */
+export function errorMiddleware(err, _req, res, _next) {
+    // Only log errors in non-test environments to reduce console noise during testing
+    if (process.env.NODE_ENV !== 'test') {
+        console.error('Error:', err);
+    }
+    // Extract error details
+    const statusCode = err.statusCode || err.status || HTTP_STATUS.INTERNAL_SERVER_ERROR;
+    const message = err.message || 'An unexpected error occurred';
+    const code = err.code || (err instanceof ApiError ? err.code : 'INTERNAL_SERVER_ERROR');
+    const details = err.details;
+    // Build standardized error response
+    const response = {
+        success: false,
+        error: {
+            code,
+            message,
+            ...(details && { details }),
+            ...(process.env.NODE_ENV === 'test' && { stack: err.stack }),
+        },
+        meta: {
+            timestamp: new Date().toISOString(),
+        },
+    };
+    res.status(statusCode).json(response);
+}