Coolify MCP Server

Instructions

Implementation Reference

• src/tools/handlers.ts:91-93 (handler)

  Handler implementation for the 'get_server' tool. Requires a 'uuid' parameter and retrieves server details via the CoolifyClient GET request to `/servers/{uuid}`.

  case 'get_server':
    requireParam(args, 'uuid');
    return client.get(`/servers/${args.uuid}`);

• src/tools/definitions.ts:758-766 (schema)

  Schema definition for the 'get_server' tool, including name, description, and input schema requiring a 'uuid' string parameter.

  {
    name: 'get_server',
    description: 'Get server details by UUID',
    inputSchema: {
      type: 'object',
      properties: { uuid: { type: 'string', description: 'Server UUID' } },
      required: ['uuid']
    }
  },

• src/index.ts:36-38 (registration)

  Registration of tools list handler, which returns all tool definitions including 'get_server' via getToolDefinitions().

  this.server.setRequestHandler(ListToolsRequestSchema, async () => ({
    tools: getToolDefinitions()
  }));

• src/index.ts:41-67 (registration)

  Registration of the generic tool call handler that dispatches to handleTool(name, args), which executes the 'get_server' case.

  this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
    if (!this.client) {
      throw new McpError(ErrorCode.InternalError, 'Client not initialized');
    }
  
    const { name, arguments: args } = request.params;
  
    // Block write operations in read-only mode
    if (isReadOnlyMode() && !READ_ONLY_TOOLS.includes(name)) {
      throw new McpError(
        ErrorCode.InvalidRequest,
        `Operation '${name}' is not allowed in read-only mode. Set COOLIFY_READONLY=false to enable write operations.`
      );
    }
  
    try {
      const result = await handleTool(this.client, name, args || {});
      return {
        content: [{ type: 'text', text: JSON.stringify(result, null, 2) }]
      };
    } catch (error) {
      if (error instanceof McpError) throw error;
      
      const message = error instanceof Error ? error.message : 'Unknown error';
      throw new McpError(ErrorCode.InternalError, `Tool execution failed: ${message}`);
    }
  });

• src/tools/handlers.ts:504-508 (helper)

  Helper function requireParam used by the get_server handler to validate the presence of the 'uuid' parameter.

  function requireParam(args: ToolArgs, param: string): void {
    if (!args[param]) {
      throw new McpError(ErrorCode.InvalidParams, `${param} is required`);
    }
  }