@hanzo/platform-mcp 1.4.0

package/build/mcp/tools/postgres/postgresSaveEnvironment.js

@@ -0,0 +1,28 @@
+import { z } from "zod";
+import apiClient from "../../../utils/apiClient.js";
+import { ResponseFormatter } from "../../../utils/responseFormatter.js";
+import { createTool } from "../toolFactory.js";
+export const postgresSaveEnvironment = createTool({
+    name: "postgres-saveEnvironment",
+    description: "Saves environment variables for a PostgreSQL database in Platform.",
+    schema: z.object({
+        postgresId: z
+            .string()
+            .describe("The ID of the PostgreSQL database to save environment for."),
+        env: z
+            .string()
+            .nullable()
+            .optional()
+            .describe("Environment variables to save for the PostgreSQL database."),
+    }),
+    annotations: {
+        title: "Save PostgreSQL Environment",
+        destructiveHint: true,
+        idempotentHint: false,
+        openWorldHint: true,
+    },
+    handler: async (input) => {
+        const response = await apiClient.post("/postgres.saveEnvironment", input);
+        return ResponseFormatter.success(`Environment variables for PostgreSQL database "${input.postgresId}" saved successfully`, response.data);
+    },
+});

package/build/mcp/tools/postgres/postgresSaveExternalPort.js

@@ -0,0 +1,27 @@
+import { z } from "zod";
+import apiClient from "../../../utils/apiClient.js";
+import { ResponseFormatter } from "../../../utils/responseFormatter.js";
+import { createTool } from "../toolFactory.js";
+export const postgresSaveExternalPort = createTool({
+    name: "postgres-saveExternalPort",
+    description: "Saves external port configuration for a PostgreSQL database in Platform.",
+    schema: z.object({
+        postgresId: z
+            .string()
+            .describe("The ID of the PostgreSQL database to configure."),
+        externalPort: z
+            .number()
+            .nullable()
+            .describe("The external port number to expose the database on."),
+    }),
+    annotations: {
+        title: "Save PostgreSQL External Port",
+        destructiveHint: true,
+        idempotentHint: false,
+        openWorldHint: true,
+    },
+    handler: async (input) => {
+        const response = await apiClient.post("/postgres.saveExternalPort", input);
+        return ResponseFormatter.success(`External port for PostgreSQL database "${input.postgresId}" saved successfully`, response.data);
+    },
+});

package/build/mcp/tools/postgres/postgresStart.js

@@ -0,0 +1,23 @@
+import { z } from "zod";
+import apiClient from "../../../utils/apiClient.js";
+import { ResponseFormatter } from "../../../utils/responseFormatter.js";
+import { createTool } from "../toolFactory.js";
+export const postgresStart = createTool({
+    name: "postgres-start",
+    description: "Starts a PostgreSQL database in Platform.",
+    schema: z.object({
+        postgresId: z
+            .string()
+            .describe("The ID of the PostgreSQL database to start."),
+    }),
+    annotations: {
+        title: "Start PostgreSQL Database",
+        destructiveHint: true,
+        idempotentHint: false,
+        openWorldHint: true,
+    },
+    handler: async (input) => {
+        const response = await apiClient.post("/postgres.start", input);
+        return ResponseFormatter.success(`PostgreSQL database "${input.postgresId}" started successfully`, response.data);
+    },
+});

package/build/mcp/tools/postgres/postgresStop.js

@@ -0,0 +1,23 @@
+import { z } from "zod";
+import apiClient from "../../../utils/apiClient.js";
+import { ResponseFormatter } from "../../../utils/responseFormatter.js";
+import { createTool } from "../toolFactory.js";
+export const postgresStop = createTool({
+    name: "postgres-stop",
+    description: "Stops a PostgreSQL database in Platform.",
+    schema: z.object({
+        postgresId: z
+            .string()
+            .describe("The ID of the PostgreSQL database to stop."),
+    }),
+    annotations: {
+        title: "Stop PostgreSQL Database",
+        destructiveHint: true,
+        idempotentHint: false,
+        openWorldHint: true,
+    },
+    handler: async (input) => {
+        const response = await apiClient.post("/postgres.stop", input);
+        return ResponseFormatter.success(`PostgreSQL database "${input.postgresId}" stopped successfully`, response.data);
+    },
+});

package/build/mcp/tools/postgres/postgresUpdate.js

@@ -0,0 +1,97 @@
+import { z } from "zod";
+import apiClient from "../../../utils/apiClient.js";
+import { ResponseFormatter } from "../../../utils/responseFormatter.js";
+import { createTool } from "../toolFactory.js";
+export const postgresUpdate = createTool({
+    name: "postgres-update",
+    description: "Updates an existing PostgreSQL database in Platform.",
+    schema: z.object({
+        postgresId: z
+            .string()
+            .min(1)
+            .describe("The ID of the PostgreSQL database to update."),
+        name: z
+            .string()
+            .min(1)
+            .optional()
+            .describe("The new name of the PostgreSQL database."),
+        appName: z
+            .string()
+            .optional()
+            .describe("The new app name of the PostgreSQL database."),
+        databaseName: z
+            .string()
+            .min(1)
+            .optional()
+            .describe("The new database name."),
+        databaseUser: z
+            .string()
+            .min(1)
+            .optional()
+            .describe("The new database username."),
+        databasePassword: z
+            .string()
+            .optional()
+            .describe("The new database password."),
+        description: z
+            .string()
+            .nullable()
+            .optional()
+            .describe("The new description for the PostgreSQL database."),
+        dockerImage: z
+            .string()
+            .optional()
+            .describe("The new Docker image for PostgreSQL."),
+        command: z
+            .string()
+            .nullable()
+            .optional()
+            .describe("Custom command to run the PostgreSQL database."),
+        env: z
+            .string()
+            .nullable()
+            .optional()
+            .describe("Environment variables for the PostgreSQL database."),
+        memoryReservation: z
+            .string()
+            .nullable()
+            .optional()
+            .describe("Memory reservation for the PostgreSQL database."),
+        externalPort: z
+            .number()
+            .nullable()
+            .optional()
+            .describe("External port for the PostgreSQL database."),
+        memoryLimit: z
+            .string()
+            .nullable()
+            .optional()
+            .describe("Memory limit for the PostgreSQL database."),
+        cpuReservation: z
+            .string()
+            .nullable()
+            .optional()
+            .describe("CPU reservation for the PostgreSQL database."),
+        cpuLimit: z
+            .string()
+            .nullable()
+            .optional()
+            .describe("CPU limit for the PostgreSQL database."),
+        applicationStatus: z
+            .enum(["idle", "running", "done", "error"])
+            .optional()
+            .describe("Application status."),
+        createdAt: z.string().optional().describe("Creation date."),
+        projectId: z.string().optional().describe("Project ID."),
+    }),
+    annotations: {
+        title: "Update PostgreSQL Database",
+        destructiveHint: true,
+        idempotentHint: false,
+        openWorldHint: true,
+    },
+    handler: async (input) => {
+        const response = await apiClient.post("/postgres.update", input);
+        return ResponseFormatter.success(`PostgreSQL database "${input.postgresId}" updated successfully`, response.data);
+    },
+});

package/build/mcp/tools/project/index.js

@@ -0,0 +1,6 @@
+export { projectAll } from "./projectAll.js";
+export { projectOne } from "./projectOne.js";
+export { projectCreate } from "./projectCreate.js";
+export { projectUpdate } from "./projectUpdate.js";
+export { projectDuplicate } from "./projectDuplicate.js";
+export { projectRemove } from "./projectRemove.js";

package/build/mcp/tools/project/projectAll.js

@@ -0,0 +1,68 @@
+import { z } from "zod";
+import apiClient from "../../../utils/apiClient.js";
+import { ResponseFormatter } from "../../../utils/responseFormatter.js";
+import { createTool } from "../toolFactory.js";
+export const projectAll = createTool({
+    name: "project-all",
+    description: "Lists all projects in Platform with optimized response size suitable for LLM consumption. Returns summary data including project info, service counts, and basic service details.",
+    schema: z.object({}),
+    annotations: {
+        title: "List All Projects",
+        readOnlyHint: true,
+        idempotentHint: true,
+        openWorldHint: true,
+    },
+    handler: async () => {
+        const response = await apiClient.get("/project.all");
+        if (!response?.data) {
+            return ResponseFormatter.error("Failed to fetch projects", "No response data received");
+        }
+        const projects = response.data;
+        // Always return optimized summary data
+        const optimizedProjects = projects.map((project) => ({
+            projectId: project.projectId,
+            name: project.name,
+            description: project.description,
+            createdAt: project.createdAt,
+            organizationId: project.organizationId,
+            // Service counts instead of full data
+            serviceCounts: {
+                applications: project.applications?.length || 0,
+                postgres: project.postgres?.length || 0,
+                mysql: project.mysql?.length || 0,
+                mariadb: project.mariadb?.length || 0,
+                mongo: project.mongo?.length || 0,
+                redis: project.redis?.length || 0,
+                compose: project.compose?.length || 0,
+            },
+            // Basic service summaries (only essential info)
+            services: {
+                applications: project.applications?.map((app) => ({
+                    applicationId: app.applicationId,
+                    name: app.name,
+                    appName: app.appName,
+                    applicationStatus: app.applicationStatus,
+                    sourceType: app.sourceType,
+                    buildType: app.buildType,
+                    domainCount: app.domains?.length || 0,
+                })) || [],
+                postgres: project.postgres?.map((db) => ({
+                    postgresId: db.postgresId,
+                    name: db.name,
+                    appName: db.appName,
+                    applicationStatus: db.applicationStatus,
+                    databaseName: db.databaseName,
+                })) || [],
+                compose: project.compose?.map((comp) => ({
+                    composeId: comp.composeId,
+                    name: comp.name,
+                    appName: comp.appName,
+                    composeStatus: comp.composeStatus,
+                    sourceType: comp.sourceType,
+                    domainCount: comp.domains?.length || 0,
+                })) || [],
+            },
+        }));
+        return ResponseFormatter.success("Successfully fetched projects summary", optimizedProjects);
+    },
+});

package/build/mcp/tools/project/projectCreate.js

@@ -0,0 +1,30 @@
+import { z } from "zod";
+import apiClient from "../../../utils/apiClient.js";
+import { createTool } from "../toolFactory.js";
+import { ResponseFormatter } from "../../../utils/responseFormatter.js";
+export const projectCreate = createTool({
+    name: "project-create",
+    description: "Creates a new project in Platform.",
+    schema: z.object({
+        name: z.string().min(1).describe("The name of the project."),
+        description: z
+            .string()
+            .nullable()
+            .optional()
+            .describe("An optional description for the project."),
+        env: z
+            .string()
+            .optional()
+            .describe("Optional environment variables for the project."),
+    }),
+    annotations: {
+        title: "Create Project",
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: true,
+    },
+    handler: async (input) => {
+        const response = await apiClient.post("/project.create", input);
+        return ResponseFormatter.success(`Project "${input.name}" created successfully`, response.data);
+    },
+});

package/build/mcp/tools/project/projectDuplicate.js

@@ -0,0 +1,54 @@
+import { z } from "zod";
+import apiClient from "../../../utils/apiClient.js";
+import { ResponseFormatter } from "../../../utils/responseFormatter.js";
+import { createTool } from "../toolFactory.js";
+const serviceSchema = z.object({
+    id: z.string().describe("The ID of the service."),
+    type: z
+        .enum([
+        "application",
+        "postgres",
+        "mariadb",
+        "mongo",
+        "mysql",
+        "redis",
+        "compose",
+    ])
+        .describe("The type of the service."),
+});
+export const projectDuplicate = createTool({
+    name: "project-duplicate",
+    description: "Duplicates an existing project in Platform with optional service selection.",
+    schema: z.object({
+        sourceProjectId: z
+            .string()
+            .min(1)
+            .describe("The ID of the source project to duplicate."),
+        name: z
+            .string()
+            .min(1)
+            .describe("The name for the new duplicated project."),
+        description: z
+            .string()
+            .optional()
+            .describe("An optional description for the duplicated project."),
+        includeServices: z
+            .boolean()
+            .default(true)
+            .describe("Whether to include services in the duplication. Defaults to true."),
+        selectedServices: z
+            .array(serviceSchema)
+            .optional()
+            .describe("Array of specific services to include. When includeServices is true and this is not provided, you MUST first retrieve all services from the source project and include ALL of them in this array. Services are not automatically included - you must explicitly list each service with its ID and type."),
+    }),
+    annotations: {
+        title: "Duplicate Project",
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: true,
+    },
+    handler: async (input) => {
+        const response = await apiClient.post("/project.duplicate", input);
+        return ResponseFormatter.success(`Project "${input.name}" duplicated successfully from source project "${input.sourceProjectId}"`, response.data);
+    },
+});

package/build/mcp/tools/project/projectOne.js

@@ -0,0 +1,24 @@
+import { z } from "zod";
+import apiClient from "../../../utils/apiClient.js";
+import { createTool } from "../toolFactory.js";
+import { ResponseFormatter } from "../../../utils/responseFormatter.js";
+export const projectOne = createTool({
+    name: "project-one",
+    description: "Gets a specific project by its ID in Platform.",
+    schema: z.object({
+        projectId: z.string().describe("The ID of the project to retrieve."),
+    }),
+    annotations: {
+        title: "Get Project Details",
+        readOnlyHint: true,
+        idempotentHint: true,
+        openWorldHint: true,
+    },
+    handler: async (input) => {
+        const project = await apiClient.get(`/project.one?projectId=${input.projectId}`);
+        if (!project?.data) {
+            return ResponseFormatter.error("Failed to fetch project", `Project with ID "${input.projectId}" not found`);
+        }
+        return ResponseFormatter.success(`Successfully fetched project "${input.projectId}"`, project.data);
+    },
+});

package/build/mcp/tools/project/projectRemove.js

@@ -0,0 +1,21 @@
+import { z } from "zod";
+import apiClient from "../../../utils/apiClient.js";
+import { createTool } from "../toolFactory.js";
+import { ResponseFormatter } from "../../../utils/responseFormatter.js";
+export const projectRemove = createTool({
+    name: "project-remove",
+    description: "Removes/deletes an existing project in Platform.",
+    schema: z.object({
+        projectId: z.string().min(1).describe("The ID of the project to remove."),
+    }),
+    annotations: {
+        title: "Remove Project",
+        destructiveHint: true,
+        idempotentHint: false,
+        openWorldHint: true,
+    },
+    handler: async (input) => {
+        const response = await apiClient.post("/project.remove", input);
+        return ResponseFormatter.success(`Project "${input.projectId}" removed successfully`, response.data);
+    },
+});

package/build/mcp/tools/project/projectUpdate.js

@@ -0,0 +1,39 @@
+import { z } from "zod";
+import apiClient from "../../../utils/apiClient.js";
+import { createTool } from "../toolFactory.js";
+import { ResponseFormatter } from "../../../utils/responseFormatter.js";
+export const projectUpdate = createTool({
+    name: "project-update",
+    description: "Updates an existing project in Platform.",
+    schema: z.object({
+        projectId: z.string().min(1).describe("The ID of the project to update."),
+        name: z.string().min(1).optional().describe("The new name of the project."),
+        description: z
+            .string()
+            .nullable()
+            .optional()
+            .describe("The new description for the project."),
+        createdAt: z
+            .string()
+            .optional()
+            .describe("The creation date of the project."),
+        organizationId: z
+            .string()
+            .optional()
+            .describe("The organization ID of the project."),
+        env: z
+            .string()
+            .optional()
+            .describe("Environment variables for the project."),
+    }),
+    annotations: {
+        title: "Update Project",
+        destructiveHint: true,
+        idempotentHint: false,
+        openWorldHint: true,
+    },
+    handler: async (input) => {
+        const response = await apiClient.post("/project.update", input);
+        return ResponseFormatter.success(`Project "${input.projectId}" updated successfully`, response.data);
+    },
+});

package/build/mcp/tools/toolFactory.js

@@ -0,0 +1,60 @@
+import apiClient from "../../utils/apiClient.js";
+import { createLogger } from "../../utils/logger.js";
+import { ResponseFormatter } from "../../utils/responseFormatter.js";
+const logger = createLogger("ToolFactory");
+export function createToolContext() {
+    return {
+        apiClient,
+        logger,
+    };
+}
+export function createTool(definition) {
+    return {
+        ...definition,
+        handler: async (input) => {
+            const context = createToolContext();
+            try {
+                // Validate input against schema
+                const validationResult = definition.schema.safeParse(input);
+                if (!validationResult.success) {
+                    context.logger.warn(`Input validation failed for tool: ${definition.name}`, {
+                        errors: validationResult.error.errors,
+                        input,
+                    });
+                    const errorMessages = validationResult.error.errors
+                        .map((err) => `${err.path.join(".")}: ${err.message}`)
+                        .join(", ");
+                    return ResponseFormatter.error(`Invalid input for tool: ${definition.name}`, `Validation errors: ${errorMessages}`);
+                }
+                context.logger.info(`Executing tool: ${definition.name}`, {
+                    input: validationResult.data,
+                });
+                const result = await definition.handler(validationResult.data);
+                context.logger.info(`Tool executed successfully: ${definition.name}`);
+                return result;
+            }
+            catch (error) {
+                context.logger.error(`Tool execution failed: ${definition.name}`, {
+                    error: error instanceof Error ? error.message : "Unknown error",
+                    input,
+                });
+                // More specific error handling based on error types
+                if (error instanceof Error) {
+                    if (error.message.includes("401") ||
+                        error.message.includes("Unauthorized")) {
+                        return ResponseFormatter.error(`Authentication failed for tool: ${definition.name}`, "Please check your PLATFORM_API_KEY configuration");
+                    }
+                    if (error.message.includes("404") ||
+                        error.message.includes("Not Found")) {
+                        return ResponseFormatter.error(`Resource not found`, `The requested resource for ${definition.name} could not be found`);
+                    }
+                    if (error.message.includes("500") ||
+                        error.message.includes("Internal Server Error")) {
+                        return ResponseFormatter.error(`Server error occurred`, `Platform server encountered an internal error while processing ${definition.name}`);
+                    }
+                }
+                return ResponseFormatter.error(`Failed to execute tool: ${definition.name}`, `Error: ${error instanceof Error ? error.message : "Unknown error occurred"}`);
+            }
+        },
+    };
+}

package/build/server.js

@@ -0,0 +1,12 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { allTools } from "./mcp/tools/index.js";
+export function createServer() {
+    const server = new McpServer({
+        name: "platform",
+        version: "1.0.0",
+    });
+    for (const tool of allTools) {
+        server.tool(tool.name, tool.description, tool.schema.shape, tool.handler);
+    }
+    return server;
+}

package/build/types/platform.js

@@ -0,0 +1,3 @@
+// Basic types for Platform API responses
+// These are minimal interfaces to avoid 'any' usage while maintaining flexibility
+export {};

package/build/utils/apiClient.js

@@ -0,0 +1,126 @@
+import axios from "axios";
+import { getClientConfig } from "./clientConfig.js";
+import { createLogger } from "./logger.js";
+// Create logger instance for axios client
+const logger = createLogger("AxiosClient");
+// Get configuration from existing client config
+const config = getClientConfig();
+// Default headers for MCP server context
+const DEFAULT_HEADERS = {
+    "Content-Type": "application/json",
+    Accept: "application/json",
+    "x-api-key": config.authToken, // Use the same auth mechanism as httpClient
+};
+// Create axios instance with configuration from clientConfig
+const apiClient = axios.create({
+    baseURL: config.platformUrl,
+    timeout: config.timeout,
+    headers: DEFAULT_HEADERS,
+});
+// Request interceptor - Add request timing and logging
+apiClient.interceptors.request.use((config) => {
+    // Add request timestamp for performance monitoring
+    config.metadata = { startTime: Date.now() };
+    logger.debug("Making API request", {
+        method: config.method?.toUpperCase(),
+        url: config.url,
+        baseURL: config.baseURL,
+        hasData: !!config.data,
+    });
+    return config;
+}, (error) => {
+    logger.error("Request interceptor error", { error: error.message });
+    return Promise.reject(error);
+});
+// Response interceptor - Handle responses and errors with proper logging
+apiClient.interceptors.response.use((response) => {
+    // Log response time for performance monitoring
+    const metadata = response.config.metadata;
+    const startTime = metadata?.startTime;
+    if (startTime) {
+        const duration = Date.now() - startTime;
+        logger.info("API request completed", {
+            method: response.config.method?.toUpperCase(),
+            url: response.config.url,
+            status: response.status,
+            duration: `${duration}ms`,
+        });
+    }
+    return response;
+}, (error) => {
+    const { response, request, config } = error;
+    // Handle different error scenarios with proper logging
+    if (response) {
+        // Server responded with error status
+        handleServerError(response);
+    }
+    else if (request) {
+        // Request was made but no response received
+        handleNetworkError(request, config);
+    }
+    else {
+        // Something else happened
+        handleUnknownError(error);
+    }
+    return Promise.reject(error);
+});
+// Helper Functions
+function handleServerError(response) {
+    const { status, data, config } = response;
+    const errorContext = {
+        status,
+        method: config?.method?.toUpperCase(),
+        url: config?.url,
+        message: data?.message || data?.error || "Unknown server error",
+    };
+    switch (status) {
+        case 401:
+            logger.error("Authentication failed - Invalid or expired API key", errorContext);
+            break;
+        case 403:
+            logger.error("Access forbidden - Insufficient permissions", errorContext);
+            break;
+        case 404:
+            logger.error("Resource not found", errorContext);
+            break;
+        case 422:
+            logger.error("Validation error", {
+                ...errorContext,
+                errors: data?.errors,
+            });
+            break;
+        case 500:
+            logger.error("Internal server error", errorContext);
+            break;
+        default:
+            logger.error(`Server error (${status})`, errorContext);
+    }
+}
+function handleNetworkError(_request, config) {
+    logger.error("Network error - Request failed", {
+        method: config?.method?.toUpperCase(),
+        url: config?.url || "Unknown URL",
+        timeout: config?.timeout || "No timeout set",
+        error: "No response received from server",
+    });
+}
+function handleUnknownError(error) {
+    logger.error("Unknown error occurred", {
+        error: error.message,
+        stack: error.stack,
+    });
+}
+// Utility function to update auth token (for MCP context)
+export function setAuthToken(token) {
+    // Update default headers for future requests
+    apiClient.defaults.headers.common["x-api-key"] = token;
+    logger.info("Auth token updated for API client");
+}
+// Utility function to clear auth token
+export function clearAuthToken() {
+    // Remove authorization header
+    delete apiClient.defaults.headers.common["x-api-key"];
+    logger.info("Auth token cleared from API client");
+}
+// Export the configured axios instance
+export default apiClient;